1HISTGR(3NCARG) NCAR GRAPHICS HISTGR(3NCARG)
2
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
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
19 CALL HISTGR (DAT1,NDIM,NPTS,IFLAG,CLASS,NCLASS,WRK,NWRK)
20
22 #include <ncarg/ncargC.h>
23 void c_histgr (float *dat1, int ndim, int npts,
25 int iflag, float *class, int nclass, float *wrk, int nwrk)
26
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 NDIM The size of the first dimension of DAT1 as set in the
36 dimension statement of the calling program.
37 NPTS Number of values actually stored into DAT1 on this call.
39 NPTS must always be less than or equal to NDIM.
40 IFLAG An integer flag which selects one of four options provided
42 by the HISTGR utility. The options are:
43 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 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 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 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 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 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 CLASS Real array containing class values, dimensioned (NCLASS+1).
107 This array has the following IFLAG dependencies:
108 IFLAG = 0 CLASS is not used.
110 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 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 IFLAG = 3 Same as for IFLAG = 2.
124 NCLASS Number of class intervals (histogram bars) specified.
126 NCLASS must be .GE. 1.
127 WRK Real scratch array, dimensioned by NWRK in the dimension
129 statement of the calling program.
130 NWRK The dimension size of array WRK determined from: NDIM + 3 *
132 (NCLASS + 1)
133
135 The C-binding argument descriptions are the same as the FORTRAN
136 argument descriptions with the following exceptions:
137 dat1 Two dimensional real array dimensioned: dat1(2,ndim).
140 ndim The size of the second dimension of dat1 as set in the
142 dimension statement of the calling program.
143
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
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
158 To use HISTGR or c_histgr, load the NCAR Graphics libraries ncarg,
159 ncarg_gks, and ncarg_c, preferably in that order.
160
162 See the histogram man page for a description of all Histogram error
163 messages and/or informational messages.
164
166 Online: histogram, histogram_params, hstopc, hstopi, hstopl, hstopr,
167 ncarg_cbind
168 Hardcopy: NCAR Graphics Fundamentals, UNIX Version
170
172 Copyright (C) 1987-2007
173 University Corporation for Atmospheric Research
174 This documentation is free software; you can redistribute it and/or
176 modify it under the terms of the GNU General Public License as
177 published by the Free Software Foundation; either version 2 of the
178 License, or (at your option) any later version.
179 This software is distributed in the hope that it will be useful, but
181 WITHOUT ANY WARRANTY; without even the implied warranty of
182 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
183 General Public License for more details.
184 You should have received a copy of the GNU General Public License along
186 with this software; if not, write to the Free Software Foundation,
187 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
188UNIX March 1993 HISTGR(3NCARG)