NAME

       HSTOPR - Specifies various REAL arrays to be used by the the Histogram utility.

SYNOPSIS

       CALL HSTOPR (STRING,ARRAY,LARR)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_hstopr (char *string, float *array, int larr)

DESCRIPTION

       STRING      Character, input -- Selects an internal parameter.  The possibilities are:

                     ´WIN=ON´ or ´WIN=OFF´
                     ´SPA=ON´ or ´SPA=OFF´
                     ´MVA=ON´ or ´MVA=OFF´

                   WIN  defines  the  portion  of  the frame that will receive the histogram. SPA determines the
                   spacing between histogram bars.  MVA requests a test to detect  input  special  values  which
                   denote missing data.

       ARRAY       Real, input -- It has a different use depending upon which parameter is specified by argument
                   STRING.  See the examples following argument LARR.

       LARR        Integer, input -- Dimension of ARRAY.

                   The following arrays may be defined by this routine:

                   Windowing:

                    STRING is ´WIN=ON´
                    LARR = 4
                    ARRAY(1) = XMIN
                    ARRAY(2) = XMAX
                    ARRAY(3) = YMIN
                    ARRAY(4) = YMAX

                   These  coordinates  define a rectangular region of the total frame in NDC´s where the current
                   histogram is to be plotted. The range of  allowed  values  is  between  0.  and  1.  in  both
                   dimensions.

                   For example, XMIN=0., XMAX=.5, YMIN=.5, and YMAX=1.  would specify the upper left quadrant of
                   the frame.

                   IF ´WIN=OFF´, the default window for the histogram will be the entire frame.

                   Spacing:

                    STRING is ´SPA=ON´
                    LARR = 2
                    ARRAY(1) = SPAC
                    ARRAY(2) = OVERLP

                   SPAC  determines  the  spacing  of  histogram  bars between 0.  (no spacing) and 4.  (maximum
                   spacing).  Default spacing is SPAC = 2.0.

                   OVERLP determines the overlap of adjacent histogram bars  when  two  datasets  are  compared.
                   Valid values are -4.0 (maximum overlap) to 4.0 (little or no overlap).  The Default is 0.

                   When STRING = ´SPA=OFF´, there is no spacing or overlap.

                   Detecting missing values:

                    STRING is ´MVA=ON´
                    LARR = 2
                    ARRAY(1) = SETMVA
                    ARRAY(2) = SETEPS

                   SETMVA is the special value used to denote missing data.  The default value is -9999.

                   SETEPS  is  an  epsilon  to  use in the special value test.  If the difference between a data
                   point and SETMVA is less than SETEPS, then the data point is assumed to be a  missing  value.
                   The Default is 1.E-10.

                   When STRING = ´MVA=OFF´, there is no testing for missing values.

C-BINDING DESCRIPTION

       The C-binding argument descriptions are the same as the FORTRAN argument descriptions.

USAGE

       HSTOPR  is called to set parameters of type REAL before entry HISTGR is called to generate the histogram.
       Options are the portion of the frame to receive the graphic, and the amount of  spacing  and  overlap  of
       histogram bars.

       For a complete list of parameters available in this utility, see the histogram_params man page.

EXAMPLES

       Use  the  command "ncargex thstgr" to generate a three frame example of histogram options.  The following
       code defined the window and bar spacing of plot 1 on frame 3.

       C
       C  Plot 1 goes into the top left quadrant of the frame.
       C
       C       ARR7 coordinates are XMIN, XMAX, YMIN, YMAX.
       C
             ARR7(1) = 0.
             ARR7(2) = .5
             ARR7(3) = .5
             ARR7(4) = 1.
             CALL HSTOPR(´WIN=ON´,ARR7,4)
       C
             SPAC(1) = 3.0
             SPAC(2) = 0.0
             CALL HSTOPR(´SPA=ON´,SPAC,2)

       Example  "ncargex thstmv" shows three examples of histograms with missing values in the input data.

ACCESS

       To use HSTOPR or c_hstopr, 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, 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.

UNIX                                               March 1993                                     HSTOPR(3NCARG)