.\

cghistogram.pro

top cgHistogram

General

result = cgHistogram(data [, BINSIZE=BINSIZE] [, /FREQUENCY] [, INPUT=INPUT] [, /L64] [, LOCATIONS=LOCATIONS] [, MAX=MAX] [, MIN=MIN] [, MISSING=MISSING] [, /NAN] [, NBINS=integer] [, OMAX=OMAX] [, OMIN=OMIN] [, REVERSE_INDICES=REVERSE_INDICES] [, SMOOTH=integer])

This program is used as a wrapper to the Histogram command in IDL. It works around a bug in the Histogram command when byte data is binned in versions prior to IDL 8.2, and it takes care to match the data type of the BinSize keyword to the data type of the data being binned. If this matching is not done, Histogram silently returns incorrect results. I have added the ability to smooth the data (with the Smooth keyword) and to return the relative frequency of the histogram, rather than the histogram counts (with the Frequency keyword). The relative frequency is a number between 0 and 1. I have also added the ability to specify "missing" data that should not be binned.

Parameters

data in required

The data from which the histogram is created.

Keywords

BINSIZE in optional

The binsize of the histogram. By default, Scott's Choice of bin size for histograms is used:

   binsize = (3.5 * StdDev(data)) / N_Elements(data)^(0.3333)

If BINSIZE in not defined, and NBINS is defined, the BINSIZE is calcuated as:

    binsize = (Max(dataToHistogram) - Min(dataToHistogram)) / (NBINS -1)

While it is pointed out in the HISTOGRAM documentation, it is extremely important that the BINSIZE be of the same data type as the data you are going to calculate the histogram of. If it is not, VERY strange things can happen, but the worst is that HISTOGRAM silently returns incorrect results. I try hard to avoid this result in this program.

FREQUENCY in optional type=boolean default=0

If this keyword is set, the relative frequency is returned, rather than the histogram counts. Relative frequency is a number between 0 and 1. The total of all the relative frequencies should equal 1.0.

INPUT in optional

Set this keyword to a named variable that contains an array to be added to the output of cgHistogram. The density function of data is added to the existing contents of Input and returned as the result. The array is converted to longword type if necessary and must have at least as many elements as are required to form the histogram. Multiple histograms can be efficiently accumulated by specifying partial sums via this keyword.

L64 in optional type=boolean default=0

If set, the return value of HISTOGRAM are 64-bit integers, rather than the default 32-bit integers. Set by default if 64-bit integers are passed in.

LOCATIONS out optional

Starting locations of each bin. Locations has the same number of elements as the result, and has the same data type as the input data array.

MAX in optional

The maximum value to use in calculating input histogram.

MIN in optional

The minimum value to use in calculating input histogram.

MISSING in optional

The value that should be represented as "missing" and not used in the histogram. Be aware that if the input data is not of type "float" or "double" that the input data will be converted to floating point prior to calculating the histogram.

NAN in optional type=boolean default=0

If set, ignore NAN values in calculating and plotting histogram. Set by default if the Missing keyword is used.

NBINS in optional type=integer

The number of output bins in the histogram. The meaning is slightly different from the meaning in the HISTOGRAM command. Used only to calculate BINSIZE when BINSIZE is not specified. In this case, binsize = rangeofData/(nbins-1). When the number of bins is low, the results can be non-intuitive. For this reason, I would discourage the use of NBins in favor of the BinSize keyword.

OMAX out optional

The maximum output value used to construct the histogram. (See HISTOGRAM documentation.)

OMIN out optional

The minimum output value used to construct the histogram. (See HISTOGRAM documentation.)

REVERSE_INDICES out optional

The list of reverse indices returned from the HISTOGRAM command. (See HISTOGRAM documentation.)

SMOOTH in optional type=integer default=0

Set this keyword to an odd positive integer to smooth the histogram output before plotting. The integer will set the width of a smoothing box to be applied to the histogram data with the Smooth function. This keyword is ignored if the Frequency keyword is set.

Examples

Create a normal distribution of random numbers and take the histogram:

  numbers = RandomU(-3L, 1000, /Normal)
  histResults = cgHistogram(numbers, Binsize=0.25)
  cgPlot, histResults

Additional examples of histogram plots can be found here:

   http://www.idlcoyote.com/gallery/index.html

Author information

Author:

FANNING SOFTWARE CONSULTING:

   David W. Fanning
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com

Copyright:

History:

Change History:

  Written by:  David W. Fanning, 7 March 2013.

File attributes

Modification date:	Fri Mar 27 11:07:36 2015
Lines:	297
Docformat:	rst rst

Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015