bvhist - compute univariate, bivariate, or trivariate histograms

bvhist - Compute univariate, bivariate, or trivariate histograms

SYNOPSIS

bvhist  [ parameter=value ... ]  [ inputfile outputfile ]
bvhist  [ parameter=value ... ]  [ inputfile ... directory ]

Parameters are: hist_vars, bin_counts, estimate_range, range_pairs, count_outside, log_scale, unit_scale, lookup_table, bin_centers

DESCRIPTION

bvhist computes univariate, bivariate and trivariate histograms. Bivariate histograms are grids that can be displayed as images. Trivariate histograms are cubes.

For a given input dataset, the corresponding output dataset will contain a histogram variable, plus one value variable for each dimension of the histogram. For example, if computing a bivariate histogram based on two input variables A and B, the output dataset will contain three variables, histogram, A, and B. The values of output value variables A and B will correspond to the bins used to compute the histogram.

The output histogram variable is either

a long integer variable, containing bin counts, or
a single precision floating point variable, containing log10(bin count +1), or
a byte-value lookup table variable, for generating histogram-equalized images

Log scaling is useful when histogram counts vary by more than two or three orders of magnitude. If histogram is a long integer variable, it can optionally be scaled by 1/maximum bin count.

PARAMETERS

hist_vars: Names of the one, two or three variables to be histogrammed. There are no defaults. Wildcards cannot be used. The first dimension of the output histogram will corresponding to the first variable. The second dimension will correspond to the second variable.
bin_counts: The number of bins for each input variable. Each number must be in the range [2, 1024]. The defaults number of bins is 256 for each variable.
estimate_range: Indicates whether or not the minimum and maximum are to be estimated for each variable. Valid responses are yes and no. The default is yes.
range_pairs: If estimate_range=no, these are min/max pairs for each input variable. If there are two input variables, four numbers must be provided. Minimums are always forced to be less than the corresponding maximums. There is no default.
count_outside: If yes, for each given variable, values below the minimum are counted in the lowest bin, and values above the maximum are counted in the highest bin. If no, variable values out of range are not counted. The default is yes.
log_scale: If yes the output histogram will be single precision floating point with values of log10(bin count +1). If no, the output histogram will lon integer bin counts. The default is yes.
unit_scale: This parameter is used only if log_scale=no. If unit_scale=yes, then a scale factor is added to the output histogram variable, causing its maximum value to be one. If unit_scale=no, the output histogram variable is left unscaled. The default is yes.
lookup_table: This parameter is used only if log_scale=no and unit_scale=no and there is only one histogram variable with no more than 256 bins. If lookup_table=yes, then the output histogram variable is converted to a byte-valued lookup table, suitable for generating histogram-equalized images. The default is no.
bin_centers: This parameter determines whether output value variables correspond to bin centers, or bin minimums. The default is no if lookup_table=yes. Otherwise, the default is yes.

EXAMPLES

The following example computes a bivariate histogram between AVHRR channels 2 and 4, first with automatic scaling, then with user-specified scaling.

% bvhist n7.84191.2316 histog
hist_vars      : char( 95) ? avhrr_ch2 avhrr_ch4
bin_counts     : int (  2) ? [256 256]
estimate_range : char(  3) ? [yes]
count_outside  : char(  3) ? [yes]
log_scale      : char(  3) ? [yes]
/extra/jhf/new7: avhrr_ch2 range [ 1.22, 27.73 ]
/extra/jhf/new7: avhrr_ch4 range [ 10.39, 49.17 ]

% bvhist n7.84191.2316 histog
hist_vars      : char( 95) ? avhrr_ch2 avhrr_ch4
bin_counts     : int (  2) ? [256 256] 60 80
estimate_range : char(  3) ? [yes] no
range_pairs    : real(  4) ? 0 30 10 50
count_outside  : char(  3) ? [yes] no
log_scale      : char(  3) ? [yes]

The following example shows how to generate a histogram equalized image from real data:

% bvhist realdata lut 
hist_vars      : char( 95) ? x
bin_counts     : int       ? [256] 255
estimate_range : char(  3) ? [yes] 
count_outside  : char(  3) ? [yes] 
log_scale      : char(  3) ? [yes] n
unit_scale     : char(  3) ? [yes] n
lookup_table   : char(  3) ? [no] y
realdata: x range [ 0, 5.07918 ]

% enhance realdata enh 
include_vars   : char(255) ? [] 
lookup_file    : char(255) ? [] lut
value_var      : char( 31) ? [value] x
index_var      : char( 31) ? [index] histogram
image_colors   : int       ? [256] 
bad_index      : int       ? [255]

NOTES

Variable values are assigned to bins using the following logic; bins are numbered starting at zero, ending at the number of bins -1:

         bin_width = (max_value - min_value)/num_bins;

         if (count_outside) {
           if (value < min_value)
             value = min_value;
           else if (value > max_value)
             value = max_value
         }

         if (value == max_value)
           bin = num_bins -1;
         else
           bin = (int)((value - min_value)/bin_width);

If the input variable data is integer values, with a range of [0, 100], and there are 10 bins, then each bin J except the last covers 10 values [J*10, ... J*10 +9]. The last bin covers 11 values [90, ..., 100].

Last Update: $Date: 2001/05/19 00:16:52 $