HISTN Function

PV-WAVE Foundation > Reference Guide > Procedure and Function Reference: H > HISTN Function

HISTN Function

Standard Library function that computes an n-dimensional histogram.

Usage

result = HISTN(d[, axes])

Input Parameters

d—An (m,n) array of m data points in n-space.

Returned Value

result—An n-dimensional array of dimensions binnum.

axes—(Optional) an n-element list containing the bin coordinate vector for each direction. For example:

CONTOUR, result, axes(0), axes(1)

Keywords

Binnum—An n-element vector giving the number of bins in each dimension.

Binsize—An n-element vector giving the size of the bins in each dimension. The default Binsize in each dimension is 1.

note	Only one of Binnum or Binsize can be set.

Range—The (2,n) array giving an expanded range for each dimension. The range must encompass that of the data. By default the range is set to the exact range of the data.

Inclusive—If set and nonzero, the last bin in each dimension is right-boundary inclusive. By default, h counts a datapoint p (i.e. d(p,*)) if a ≤ p < b where a and b are the lower and upper bin boundaries of a given bin.

Scale—If set, the result is scaled so to have unit volume under the curve/surface when plotted against x.i/stdev(x.i).

Examples

d = [-1.0, 0.0, 1.0, 1.0]

; Compare HISTOGRAM to HISTN for 1D data...

g = HISTOGRAM(d, Binsize=0.5, Min=-1, Max=1)

h1 = HISTN(d, a1, Binsize=[0.5], Range=[-1,1])

PRINT, SAME(g,h1)

; Now consider the effects of the Inclusive keyword

h2 = HISTN(d, a2, Binsize=[0.5], Range=[-1,1], /Inclusive)

; Note that if we do not use the Inclusive keyword that we

; will need 5 bins to cover the range [-1,1].

;     bin_0: -1.0 <= data < -0.5

;     bin_1: -0.5 <= data < 0.0

;     bin_2:  0.0 <= data < 0.5

;     bin_3:  0.5 <= data < 1.0

;     bin_4:  1.0 <= data < 1.5

h3 = HISTN(d, a3, Binnum=[5], Range=[-1,1])

; Now use Inclusive keyword and only 4 bins are needed to cover

; the range [-1,1], since bin_3 is now 0.5 <= data <= 1.0

h4 = HISTN(d, a4, Binnum=[4], Range=[-1,1], /Inclusive)

; Compare the results of using equivalent Binsize vs. Binnum

; constraints.

PRINT, SAME(h1, h3), SAME(h2, h4)

PRINT, SAME(a1, a3), SAME(a2, a4)