Provided by: libncarg-dev_6.6.2.dfsg.1-1_amd64 
NAME
HISTGR - Plots a histogram with various options including specification of class values,
spacing between histogram bars, shading of bars, windowing (i.e. scaling), specification
of color, labels, titles, etc. Data values are partitioned into classes; histogram bars
represent either number of occurrences within each class, or a Y-value associated with
that class (user choice). Options are set by calls to subroutines HSTOPL, HSTOPR, HSTOPC,
and HSTOPI before the call to HISTGR.
UTILITY
This routine is part of the Histogram utility in NCAR Graphics. To see the overview man
page for this utility, type "man histogram".
SYNOPSIS
CALL HISTGR (DAT1,NDIM,NPTS,IFLAG,CLASS,NCLASS,WRK,NWRK)
C-BINDING SYNOPSIS
#include <ncarg/ncargC.h>
void c_histgr (float *dat1, int ndim, int npts,
int iflag, float *class, int nclass, float *wrk, int nwrk)
DESCRIPTION
DAT1 Two dimensional real array containing data of one of two types, either values
to be collected into class intervals before plotting, or values which have
already been assigned to class intervals and only need to be displayed. See
argument IFLAG for a more complete description of HISTGR input data options.
DAT1 is dimensioned: DAT1(NDIM,2).
NDIM The size of the first dimension of DAT1 as set in the dimension statement of
the calling program.
NPTS Number of values actually stored into DAT1 on this call. NPTS must always be
less than or equal to NDIM.
IFLAG An integer flag which selects one of four options provided by the HISTGR
utility. The options are:
0 A single array of length NPTS is loaded
into the DAT1 array. HISTGR computes NCLASS
equally sized class intervals that vary
from the minimum value in DAT1 to the
maximum value in steps of (MAX-MIN)/NCLASS.
All values of DAT1 that fall in each
class interval are separately accumulated
for that interval. The final tabulations
are plotted as a histogram of NCLASS bars.
The bar height can be labeled with the
number of points that fall within this
particular class interval (bin size), or
it can be given as a percentage of the
number of values input, NPTS.
Note that under this option the user
has no control over the range of the
class intervals. They are internally
determined from the range of the data.
1 This option is similar to the IFLAG = 0
option except that the user can select
the range of the class intervals into
which the data are collected. For example,
say the user wants to collect the number
of occurrences of the DAT1 values that
fall within 5 equally spaced intervals
in the value range from 0. to 10. The
user would then input NCLASS+1 class
interval end points into array CLASS,
namely 0., 2., 4., 6., 8., and 10.
These values need not be entered in
monotonically increasing order and
need not be equally spaced.
2 This option allows the user to enter
and display data which has already
been accumulated into class intervals,
i.e., already available histograms.
The data input to DAT1 thus have
percentage of total, or number of
occurrences values. In this case the
number of points in DAT1, NPTS, is
equal to the number of class intervals
(histogram bars), NCLASS. The NCLASS
class interval midpoints are loaded
into array CLASS. They do not have
to be of equal width.
3 This option is the same as option
IFLAG = 2 except that two histograms
can be displayed for comparison
purposes. The first histogram is
loaded into DAT1(NPTS,1). The second
histogram is loaded into DAT1(NPTS,2).
The first histogram can partially
shade or obscure the second histogram
by the appropriate selection of the
SPAC and OVERLP options. Note that
NPTS = NCLASS when IFLAG = 2 or 3.
CLASS Real array containing class values, dimensioned (NCLASS+1). This array has the
following IFLAG dependencies:
IFLAG = 0 CLASS is not used.
IFLAG = 1 NCLASS+1 class interval end points
are loaded into array CLASS in a
monotonically increasing order. The
intervals need not be of equal width.
IFLAG = 2 NCLASS midpoint intervals are loaded
into array CLASS. They must be in
monotonically increasing order, but
need not be of equal widths. The
histogram bars will however be
displayed with equal widths.
IFLAG = 3 Same as for IFLAG = 2.
NCLASS Number of class intervals (histogram bars) specified. NCLASS must be .GE. 1.
WRK Real scratch array, dimensioned by NWRK in the dimension statement of the
calling program.
NWRK The dimension size of array WRK determined from: NDIM + 3 * (NCLASS + 1)
C-BINDING DESCRIPTION
The C-binding argument descriptions are the same as the FORTRAN argument descriptions with
the following exceptions:
dat1 Two dimensional real array dimensioned: dat1(2,ndim).
ndim The size of the second dimension of dat1 as set in the dimension statement of
the calling program.
USAGE
Many parameters which affect the output histogram can be set before this routine is
called. See the histogram_params man page for a short functional description of all
available parameters. For more detail on a specific option, see the man pages of the
parameter setting routines (HSTOPC, HSTOPI, HSTOPL, or HSTOPR) used to set the parameters
defining that option.
EXAMPLES
Use the command "ncargex thstgr" to generate a three frame example of various types of
histograms. "ncargex thstmv" will show three examples of histograms with missing values
in the input data.
ACCESS
To use HISTGR or c_histgr, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c,
preferably in that order.
MESSAGES
See the histogram man page for a description of all Histogram error messages and/or
informational messages.
SEE ALSO
Online: histogram, histogram_params, hstopc, hstopi, hstopl, hstopr, ncarg_cbind
Hardcopy: NCAR Graphics Fundamentals, UNIX Version
COPYRIGHT
Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.