SysTutorials

Linux Manual Pages › Section 3

ncl_histgr(3)

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.