1HISTGR(3NCARG)                   NCAR GRAPHICS                  HISTGR(3NCARG)
2
3
4

NAME

6       HISTGR - Plots a histogram with various options including specification
7       of class values, spacing between histogram bars, shading of bars,
8       windowing (i.e. scaling), specification of color, labels, titles, etc.
9       Data values are partitioned into classes; histogram bars represent
10       either number of occurrences within each class, or a Y-value associated
11       with that class (user choice).  Options are set by calls to subroutines
12       HSTOPL, HSTOPR, HSTOPC, and HSTOPI before the call to HISTGR.
13

UTILITY

15       This routine is part of the Histogram utility in NCAR Graphics. To see
16       the overview man page for this utility, type "man histogram".
17

SYNOPSIS

19       CALL HISTGR (DAT1,NDIM,NPTS,IFLAG,CLASS,NCLASS,WRK,NWRK)
20

C-BINDING SYNOPSIS

22       #include <ncarg/ncargC.h>
23
24       void c_histgr (float *dat1, int ndim, int npts,
25       int iflag, float *class, int nclass, float *wrk, int nwrk)
26

DESCRIPTION

28       DAT1        Two dimensional real array containing data of one of two
29                   types, either values to be collected into class intervals
30                   before plotting, or values which have already been assigned
31                   to class intervals and only need to be displayed. See
32                   argument IFLAG for a more complete description of HISTGR
33                   input data options. DAT1 is dimensioned: DAT1(NDIM,2).
34
35       NDIM        The size of the first dimension of DAT1 as set in the
36                   dimension statement of the calling program.
37
38       NPTS        Number of values actually stored into DAT1 on this call.
39                   NPTS must always be less than or equal to NDIM.
40
41       IFLAG       An integer flag which selects one of four options provided
42                   by the HISTGR utility. The options are:
43
44                   0    A single array of length NPTS is loaded
45                        into the DAT1 array. HISTGR computes NCLASS
46                        equally sized class intervals that vary
47                        from the minimum value in DAT1 to the
48                        maximum value in steps of (MAX-MIN)/NCLASS.
49
50                        All values of DAT1 that fall in each
51                        class interval are separately accumulated
52                        for that interval. The final tabulations
53                        are plotted as a histogram of NCLASS bars.
54                        The bar height can be labeled with the
55                        number of points that fall within this
56                        particular class interval (bin size), or
57                        it can be given as a percentage of the
58                        number of values input, NPTS.
59
60                        Note that under this option the user
61                        has no control over the range of the
62                        class intervals.  They are internally
63                        determined from the range of the data.
64
65                   1    This option is similar to the IFLAG = 0
66                        option except that the user can select
67                        the range of the class intervals into
68                        which the data are collected. For example,
69                        say the user wants to collect the number
70                        of occurrences of the DAT1 values that
71                        fall within 5 equally spaced intervals
72                        in the value range from 0. to 10. The
73                        user would then input NCLASS+1 class
74                        interval end points into array CLASS,
75                        namely 0., 2., 4., 6., 8., and 10.
76                        These values need not be entered in
77                        monotonically increasing order and
78                        need not be equally spaced.
79
80                   2    This option allows the user to enter
81                        and display data which has already
82                        been accumulated into class intervals,
83                        i.e., already available histograms.
84                        The data input to DAT1 thus have
85                        percentage of total, or number of
86                        occurrences values. In this case the
87                        number of points in DAT1, NPTS, is
88                        equal to the number of class intervals
89                        (histogram bars), NCLASS. The NCLASS
90                        class interval midpoints are loaded
91                        into array CLASS. They do not have
92                        to be of equal width.
93
94                   3    This option is the same as option
95                        IFLAG = 2 except that two histograms
96                        can be displayed for comparison
97                        purposes. The first histogram is
98                        loaded into DAT1(NPTS,1). The second
99                        histogram is loaded into DAT1(NPTS,2).
100                        The first histogram can partially
101                        shade or obscure the second histogram
102                        by the appropriate selection of the
103                        SPAC and OVERLP options.  Note that
104                        NPTS = NCLASS when IFLAG = 2 or 3.
105
106       CLASS       Real array containing class values, dimensioned (NCLASS+1).
107                   This array has the following IFLAG dependencies:
108
109                   IFLAG = 0 CLASS is not used.
110
111                   IFLAG = 1 NCLASS+1 class interval end points
112                           are loaded into array CLASS in a
113                           monotonically increasing order.  The
114                           intervals need not be of equal width.
115
116                   IFLAG = 2 NCLASS midpoint intervals are loaded
117                           into array CLASS. They must be in
118                           monotonically increasing order, but
119                           need not be of equal widths. The
120                           histogram bars will however be
121                           displayed with equal widths.
122
123                   IFLAG = 3 Same as for IFLAG = 2.
124
125       NCLASS      Number of class intervals (histogram bars) specified.
126                   NCLASS must be .GE. 1.
127
128       WRK         Real scratch array, dimensioned by NWRK in the dimension
129                   statement of the calling program.
130
131       NWRK        The dimension size of array WRK determined from: NDIM + 3 *
132                   (NCLASS + 1)
133

C-BINDING DESCRIPTION

135       The C-binding argument descriptions are the same as the FORTRAN
136       argument descriptions with the following exceptions:
137
138
139       dat1        Two dimensional real array dimensioned: dat1(2,ndim).
140
141       ndim        The size of the second dimension of dat1 as set in the
142                   dimension statement of the calling program.
143

USAGE

145       Many parameters which affect the output histogram can be set before
146       this routine is called.  See the histogram_params man page for a short
147       functional description of all available parameters.  For more detail on
148       a specific option, see the man pages of the parameter setting routines
149       (HSTOPC, HSTOPI, HSTOPL, or HSTOPR) used to set the parameters defining
150       that option.
151

EXAMPLES

153       Use the command "ncargex thstgr" to generate a three frame example of
154       various types of histograms.  "ncargex thstmv" will show three examples
155       of histograms with missing values in the input data.
156

ACCESS

158       To use HISTGR or c_histgr, load the NCAR Graphics libraries ncarg,
159       ncarg_gks, and ncarg_c, preferably in that order.
160

MESSAGES

162       See the histogram man page for a description of all Histogram error
163       messages and/or informational messages.
164

SEE ALSO

166       Online: histogram, histogram_params, hstopc, hstopi, hstopl, hstopr,
167       ncarg_cbind
168
169       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
170
172       Copyright (C) 1987-2009
173       University Corporation for Atmospheric Research
174
175       The use of this Software is governed by a License Agreement.
176
177
178
179UNIX                              March 1993                    HISTGR(3NCARG)
Impressum