DATAMANIP commands


PROGRAM NAME

khisto - Compute Histogram for Data Object

DESCRIPTION

khisto computes histograms from data objects and stores the histogram data in another data object. An independent histogram is computed and stored for each "unit" of data in the value segment of the input data object.

A unit is defined by the settings of the -w,-h,-d,-t,-e and -whole options. For example, if it is desired to compute an independent histogram for each WxH plane of a WHDTE=(512,480,1,1,256) object, then the unit we want is specified by supplying -w and -h and there will be 256 columns in the output object, each column being the histogram of a WxH plane. If we want a single histogram for the whole data object, then we can obtain that result by supplying -whole, or -w -h -e, or -w -h -d -t -e since these combinations all cause the histogram unit to span all of the data. In this case the output object will have only a single column representing the histogram of the whole data set.

Histograms are stored in the output data object as column vectors in the WxH plane, one column per histogram unit. The computed histograms are stored in the order in which the units are accessed in the index order assigned to the value segment of the input data object. For example, for a value segment with WHDTE=(512,126,48,1,1), with a HxD unit (specified by -h -d) and the default index order (WHDTE), then there will be 512 columns in the output object. The histogram for the HxD plane at (0,x,x,0,0) will be stored in column #0; that for the HxD plane at (1,x,x,0,0) will be stored in column #1, and that for the HxD plane at (N,x,x,0,0) will be stored in column #N.

Within each column, the count computed for bin #M is stored in row #M.

The histogram structure is specified by three parameters:

min side of minimum bin (starting value) This number specifies the most negative number that can be trapped in the histogram array. Another way to define it is as the lower edge of first histogram bin.

binwidth This is the width of each histogram bin.

bins This is the total number of bins to be used in the histogram.

Values are assigned to bin index [0...bins-1] using the following procedure:

bin_num = (input_val - mina) / binwidth

if (input_val == min + bins*binwidth) bin_num = bins - 1

With this arrangement, a bin collects input values ranging from the value of the left edge inclusively up to the value of the right edge exclusively. The exception is the last bin which collects values between the left and right edges inclusively (for both edges). If the computed bin_num falls outside of the array, then that data point is ignored in the histogram unless the -oob (append out-of-bounds bins) flag is supplied (described below).

If the input data object has a mask, then data points marked as invalid by the mask are ignored in the histogram calculations.

If a gate object is supplied, then only those data points with a value corresponding to non-zero in the gate image will be histogrammed. If a a gate object is supplied and the input has a mask, then data points are ignored if masked or marked for "ignore" by the gate object. The gate object must have the same value segment dimensions as the input object.

If the input data object has a map, then the data can be optionally pulled through the map before histogramming depending on the setting of the -map flag. If the input object has a map and -map is supplied, then the data will be pulled through the map before histogramming, potentially greatly multiplying the size of the data set. If the input object has a map and -map is not supplied, then the histogram operation will be carried out on the map indices since that is what is stored in the data (this may be useful for data that has been pseudocolored, for example).

If the out-of-bounds flag (-oob) is supplied, then two additional bins will be placed at the end of the histogram. The first one will contain the number of data values that fell outside of the histogram array on the low (more negative) side, and the second will contain the number of data values that fell outside the histogram array on the high (more positive) side. This option is useful when little is known about the range of the data and one is not sure if the specified range of the histogram array is capturing all of the data.

The optional integrated histogram output object conforms to the same size and structure as the histogram output object except that it is of data type KDOUBLE and each histogram has been integrated. The integrated histograms can optionally be normalized (each histogram independently) to the range [0..1].

khisto utilizes data services internally and can process large data sets. All internal calculations are done in double precision. All input data is converted to KDOUBLE by data services after being read from the input data object. The output histogram data object is of type KULONG. Complex input data is converted before histogramming by taking the real part.

REQUIRED ARGUMENTS

-i
type: infile
desc: Input data object
-o1
type: outfile
desc: histogram output data object

OPTIONAL ARGUMENTS

-igate
type: infile
desc: Gating input data object
default: {none}
-bins
type: integer
desc: number of histogram bins
default: 256
bounds: value > 0
-binwidth
type: double
desc: width of histogram bin
default: 1
bounds: no range checking
-min
type: double
desc: Min side of min histogram bin
default: 0
bounds: no range checking
-oob
type: flag
desc: append a pair of bins for out-of-bounds data
-map
type: flag
desc: if map exists, pull the value data through it
-normalize
type: flag
desc: normalize integrated histogram to [0..1]
-o2
type: outfile
desc: integrated histogram output object
default: {none}

Mutually Exclusive Group; if desired, specify ONE of:

-whole
type: flag
desc: histogram whole data set at one time
OR

AT LEAST ONE OF the Group:

-w
type: flag
desc: include width in histogram unit
AND/OR
-h
type: flag
desc: include height in histogram unit
AND/OR
-d
type: flag
desc: include depth in histogram unit
AND/OR
-t
type: flag
desc: include time in histogram unit
AND/OR
-e
type: flag
desc: include elements in histogram unit

EXAMPLES

% khisto -i clouds.seq -o h.clouds -w -h -min 0
-binwidth 1 -bins 256
will construct an interesting histogram data set from the cloud sequence. This sequence is comprised of a set of 582 512x480 frames, taken 15 seconds apart, stored as WHDTE=(512,480,1,582,1). Each frame views the same section of sky as a storm develops. The output is best visualized using editimage with the SA pseudocolor option turned on. Here, the columns of the output image are for the frames in time order, so it is easy to see how the storm phases develop, modulate, and peak during this period.

SEE ALSO

khistops(1)

RESTRICTIONS

If the input data is complex, then you may want to convert it yourself using whatever means you require; the default for complex input is to take only the real part.

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.