cdfhisto -- Creates a histogram with one to four dimensions
cdfhisto [-k] num_dims histo_name field1 low1 num1 incr1 ...
A one dimensional histogram is a set of bins into which values associated with some variable are sorted. Such a histogram would be represented in Candis as a one dimensional field with the field containing the instances of the variable of interest being the dimension of the histogram field. For instance, the field of interest might be temperature as a function of time for some location. The resulting histogram would contain, in each bin, the number of times the temperature fell within the range associated with that bin.
Two and higher dimensional histograms are possible, for instance, the number of lightning strokes in latitude-longitude bins.
The name of the dimension associated with the histogram is the name of the original variable with ‘‘-dim’’ appended. Thus, sorting by the field ‘‘theta’’ results in a dimension name ‘‘theta-dim’’. For multi-dimensional histograms, the name of each dimension is similarly associated with the corresponding variable name.
Cdfhisto creates histograms from one to four dimensions. The input fields must be commensurate, i. e., they must have the same dimensionality and size. The Candis file containing the fields must appear on the standard input. The standard output produces a Candis file that contains the histogram. Values from all elements of the fields in all variable slices are put into the same histogram.
For input files with more than one variable slice, histograms are computed for each variable slice.
The meanings of the command line arguments follow:
[-k] -- keeps the fields from the original file in the output file -- otherwise, these fields are discarded.
num_dims -- the number of dimensions the histogram, must be an integer from 1 to 4.
histo_name -- the name of the field in which the histogram will be stored.
field1 -- the name of the first dimension of the histogram. A corresponding field must be found in the input file.
low1 -- lower limit of the first bin associated with field1.
num1 -- the number of bins associated with field1.
incr1 -- the size of each bin associated with field1.
For multidimensional histograms, a field, low value, num value, and incr value must be specified for each dimension.
kestrel% cdfhisto 2 histo lat 30 10 1 long -110 10 1 < ldat > hfile
This command line would create a two dimensional histogram of lightning strikes between latitude 30 and 40 and longitude -110 and -100. Each element of the histogram would count the number of lightning strikes in a 1 by 1 degree area. The data for this file would be taken from the file ldat, and a histogram called histo would be written as a single variable slice to the file called hfile. The variable fields lat and long would be expected in the file ldat. These fields would presumably contain the latitude and longitude of a series of lightning strokes.
kestrel% cdfhisto 1 tscale temp -40 20 2 < tempsfile > savedata
This command would create a one dimensional histogram of temperatures between -40 and 0 degrees. Each element of the histogram would count the number of temperature readings in a two degree bin. The data for this file would be taken from the file tempsfile, and a histogram called tscale would be written as a single variable slice to the file called savedata. The input file is expected to have a variable field called temp, which is assumed to contain the temperatures.