>  Docs Center  >  Libraries  >  Coyote  >  CGHISTOPLOT


  This program is used to draw a histogram plot in an IDL direct graphics window..




    data: in, required,
      The data from which the histogram is created.


    addcmd: in, optional, type=boolean, default=0
      Set this keyword to add the command to the resizeable graphics window cgWindow.
    axiscolorname: in, optional, type=string, default='opposite'
      The name of the axis color. All color names are derived from cgColor.
    backcolorname: in, optional, type=string, default='background'
      The name of the background color. All color names are derived from cgColor.
    binsize: in, optional
      The binsize of the histogram. By default, Scott's Choice of bin size for histograms is used::
          binsize = (3.5 * StdDev(data)) / N_Elements(data)^(0.3333)
      If BINSIZE in not defined, and NBINS is defined, the BINSIZE is calcuated as::
            binsize = (Max(dataToHistogram) - Min(dataToHistogram)) / (NBINS -1)
      While it is pointed out in the HISTOGRAM documentation, it is extremely
      important that the BINSIZE be of the same data type as the data you are going to
      calculate the histogram of. If it is not VERY strange things can happen. I've
      tried to protect you from most of the bad things, but I don't have a high confidence
      level that I have done it for every situation. If you see something that "just don't
      look right", I would check first to see if your data types match. That might solve
      all your problems.
    charsize: in, optional, type=float
      The character size of the annotations. Default set by calling cgDefCharSize().
    datacolorname: in, optional, type=string, default="indian red"
      The name of the data color for drawing the histogram outlines.
    filename: in, optional, type=string
      The name of a color name file to use with cgCOLOR.
    fillpolygon: in, optional, type=boolean, default=0
      Set this keyword to fill the histogram polygons with the `POLYCOLOR`.
    frequency: in, optional, type=boolean, default=0
      If this keyword is set, the relative frequency is plotted on the Y axis,
      rather than the histogram density.
    histdata: out, optional
      The output value of the internal HISTOGRAM command.
    l64: in, optional, type=boolean, default=0
      If set, the return value of HISTOGRAM are 64-bit integers, rather than
      the default 32-bit integers.
    log: in, optional, type=boolean, default=0
      Set this keyword if you wish the histogram count to be represented on a logarithmic scale.
    layout: in, optional, type=integer
      This keyword specifies a grid with a graphics window and determines
      where the graphic should appear. The syntax of LAYOUT is a 3-element
      array: [ncolumns, nrows, location]. The grid is determined by the
      number of columns (ncolumns) by the number of rows (nrows). The location
      of the graphic is determined by the third number. The grid numbering
      starts in the upper left (1) and goes sequentually by column and then by row.
    line_fill: in, optional, type=boolean, default=0
      If set, the polygons are filled with lines instead of solid color. If
      this keyword is set, the following keywords can also be used: `ORIENTATION`,
    locations: out, optional
      Starting locations of each bin. (See the HISTOGRAM documentation for details.)
    maxinput: in, optional
      The maximum value to use in calculating input histogram. Equivalent to the MAX keyword
      in the HISTOGRAM documentation.
    max_value: in, optional
      The maximum Y data value to represent on graphics plot. Default: Max(data) * 1.05.
    mininput: in, optional
      The minimum value to use in calculating input histogram. Equivalent to the MIN keyword
      in the HISTOGRAM documentation.
    min_value: in, optional
      The minimum Y data value to represent on graphics plot. Default: 0.
    missing: in, optional
      The value that should be represented as "missing" and not used in the histogram.
      Be aware that if the input data is not of type "float" or "double" that the input
      data will be converted to floating point prior to calculating the histogram.
    nan: in, optional, type=boolean, default=0
      If set, ignore NAN values in calculating and plotting histogram.
    nbins: in, optional, type=integer
      The number of output bins in the histogram. Meaning is slightly different from
      meaning in the HISTOGRAM command. Used only to calculate BINSIZE when BINSIZE is
      not specified. In this case, binsize = rangeofData/(nbins-1).
    omax: out, optional
      The maximum output value used to construct the histogram. (See HISTOGRAM documentation.)
    omin: out, optional
      The minimum output value used to construct the histogram. (See HISTOGRAM documentation.)
    oprobability: in, optional, type=boolean, default=0
      Set this keyword if you want to overplot the cumulative probability on the plot.
    oplot: in, optional, type=boolean, default=0
      Set this keyword if you want to overplot the histogram on already established axes.
    orientation: in, optional, type=float, default=0.0
      The orientation (rotations) of the lines used to fill the polygons if `LINE_FILL` is set.
      (See POLYFILL documentation.)
    outfilename: in, optional, type=string
      If the `Output` keyword is set, the user will be asked to supply an output
      filename, unless this keyword is set to a non-null string. In that case, the
      value of this keyword will be used as the filename and there will be no dialog
      presented to the user.
    outline: in, optional, type=boolean, default=0
      Set this keyword if you wish to draw only the outline of the histogram plot,
      in a manner similar to setting PSYM=10 on a PLOT command.
    output: in, optional, type=string, default=""
      Set this keyword to the type of output desired. Possible values are these::
            'PS' - PostScript file
            'EPS' - Encapsulated PostScript file
            'PDF' - PDF file
            'BMP' - BMP raster file
            'GIF' - GIF raster file
            'JPEG' - JPEG raster file
            'PNG' - PNG raster file
            'TIFF' - TIFF raster file
      Or, you can simply set this keyword to the name of the output file, and the type of
      file desired will be determined by the file extension. If you use this option, the
      user will not be prompted to supply the name of the output file.
      All raster file output is created through PostScript intermediate files (the
      PostScript files will be deleted), so ImageMagick and Ghostview MUST be installed
      to produce anything other than PostScript output. (See cgPS2PDF and PS_END for
      details.) And also note that you should NOT use this keyword when doing multiple
      plots. The keyword is to be used as a convenient way to get PostScript or raster
      output for a single graphics command. Output parameters can be set with cgWindow_SetDefs.
    pattern: in, optional
      The fill pattern for the polygons if the `FILLPOLYGON` keyword is set. (See POLYFILL documentation.)
    polycolor: in, optional, type=string, default="rose"
      The name of the polygon fill color if the `FILLPOLYGON` keyword is set.
    position: in, optional, type=fltarr
      The position of the plot axes in normalized data coordinates, [x0,y0,x1,y1].
    probability_function: out, optional, type=float
      The total cummulative probability of the histogram plot, scaled from 0 to 1.
    probcolorname: in, optional, type=string, default="blue"
      The name of the probability color for overplotting the cumulative probability
      on the plot.
    probthick: in, optional, type=float, default=1.0
      The thickness of the probability line drawn on the plot.
    reverse_indices: out, optional
      The list of reverse indices returned from the HISTOGRAM command. (See HISTOGRAM documentation.)
      rotate: in, optional, type=boolean, default=0
      Set this keyword to cause the histogram bins to be drawn from left to right, rather
      than from bottom to top.
    smooth: in, optional, type=integer, default=0
      Set this keyword to an odd positive integer to smooth the histogram output before plotting.
      The integer will set the width of a smoothing box to be applied to the histogram data with
      the Smooth function.
    spacing: in, optional
      The spacing of fill line if the 'LINE_FILL` keyword is set. (See POLYFILL documentation.)
    thick: in, optional, type=integer, default=1
      Set this keyword to a value greater than 1 to draw thicker axes and lines.
    title: in, optional, type=string
        Set this keyword to the plot title.
    window: in, optional, type=boolean, default=0
        Set this keyword to replace all the commands in the current cgWindow or to
        create a new cgWindow, if one doesn't currenly exist, for displaying this command.
        To create a new cgWindow if one currenly exists, use the `cgWindow` command
    xtitle: in, optional, type=string, default="Relative Frequency"
        The X title of the histogram plot.
    ytitle: in, optional, type=string, default="Histogram Density"
        The Y title of the histogram plot.
    _ref_extra: in, optional
        Any additional PLOT commands are passed via keyword inheritance.


    Some of the ways cgHistogram can be used::
      cgHistoplot, Dist(256), BINSIZE=5.0
      cgHistoplot, Fix(RandomU(seed, 200)*20), POLYCOLOR=['charcoal', 'steel blue'], /FILLPOLYGON
      cgHistoplot, Fix(RandomU(seed, 200)*20), POLYCOLOR=['navy', 'forest green'], /LINE_FILL, ORIENTATION=[45,-45]
    Additional examples can be found here::


          David W. Fanning
          1645 Sheely Drive
          Fort Collins, CO 80526 USA
          Phone: 970-221-0438
          E-mail: david@idlcoyote.com
          Coyote's Guide to IDL Programming: http://www.idlcoyote.com


    Change History::
      Written by: David W. Fanning, 14 November 2007.
      Modified to work with !P.MULTI. 20 Nov 2007. DWF.
      Slight problem with extra space at the right end of the plot resolved. 20 Nov 2007. DWF.
      Added FILE and NOLINES keywords. 24 Nov 2007. DWF.
      Added additional HISTOGRAM access via keywords. 24 Nov 2007. DWF.
      Fixed a small problem with FILLPOLY keyword. 26 Nov 2007. DWF.
      Fixed a small problem with the OVERPLOTTED histogram being slightly offset. 12 Jan 2009. DWF
      Major reconstructive surgery on the actual drawing part of the program. As far as I can
          tell, all functionality is the same, but without drawing problems evidenced before. 14 March 2009. DWF.
      A small problem with the way I was specifying ranges caused the bars to be slightly offset. 23 March 2009. DWF.
      I fixed a small problem with BINSIZE and HISTOGRAM data type matching (see the Note), and I also
          fixed a small problem with the range calculations when byte data is passed in. 1 April 2009. DWF.
      I removed a NOLINES keyword, which was no longer being used. 1 April 2009. DWF.
      MIN_VALUE and MAX_VALUE keywords now work again, thanks to Josiah Schwab. 22 April 2009. DWF.
      Changed default POLYFILL color to "ROSE". 22 April 2009. DWF.
      Having problems with binsize selection when data to histogram is an integer type. Fixed. 8 June 2009. DWF.
      When the input array has a considerable number of NANs, the Histogram command complains with an error
          "Array has too many elements." This happens even when the NAN keyword is set for the Histogram
          command. So, I now screen for NANs before I process the histogram. 8 June 2009. DWF.
      Added MISSING keyword to represent missing data. 18 July 2009. DWF.
      Adding the MISSING keyword exposed a problem I had in restoring the original input data
          to its original values when there were NANs and MISSING values. Fixed now by making
          a copy of the data to work on internally. Everything else is too complex. 20 July 2009. DWF.
      Yikes! Bad error in calculating start and end of histogram plot when overplotting fixed. 4 Sept 2009. DWF.
      Added needed XSTYLE=1 to AXIS command to match Plot axis labelling. 19 Oct 2009. DWF.
      Added a THICK keyword. 9 November 2009. DWF.
      Added an OUTLINE keyword so only the outline of the histogram is plotted. 3 December 2009. DWF.
      I was trying to be a good citizen by reloading the input color table when I exited
            the program. But, of course, that makes it impossible to use the program in
            the Z-buffer. Fixed by being less of a good citizen. 23 July 2010. DWF.
      Because of the way I was dealing with NANs and MISSING data, the reverse indices were
            inaccurate when they were returned, if there was NANs or MISSING data in the
            input array. The data is now being handled correctly in all cases. This requires
            that missing data must be set to !VALUES.F_NAN prior to calculating the histogram.
            This means the data MUST be converted to floats for this operation. Since I am
            always working on a *copy* of the data when this occurs, it should not affect
            user input data. Also, I scan all input floating point and double data for NANs,
            and if found, and the NAN keyword is not set, I issue a warning and set the NAN
            keyword. This is a change in behavior. 1 October 2010. DWF.
      Fixed a problem when specifying more than one POLYCOLOR. I made a change to the program
            and forgot to propogate it everywhere. 4 October 2010. DWF.
      Default axis color name changed from "Navy" to "Black". 28 October 2010. DWF.
      Fixed a problem with restoring color tables in PostScript. 24 Nov 2010. DWF.
      Added OPROBABILITY, PROBCOLOR, and PROBABILITY keywords. 24 Nov 2010. DWF.
      Changed the way I find a default axis color. 3 Dec 2010. DWF.
      Expanded search for "integers" from in BINSIZE calculation from DataType LE 3
            to include DataType GE 12, too. 8 Dec 2010. DWF.
      Added WINDOW keyword. 24 Jan 2011. DWF.
      Added ADDCMD keyword. 26 Jan 2011. DWF.
      Added LAYOUT keyword. 28 Jan 2011. DWF.
      Added CHARSIZE keyword. 2 Feb 2011. DWF.
      Added YTITLE keyword. 9 May 2011. DWF.
      Worked around a PLOT problem when setting the X axis range that caused the Y axis
          range to be corrupted. 19 May 2011. DWF.
      Added the ROTATE keyword. 18 Aug 2011. DWF.
      I was calculating and displaying the cumulative probability distribution function
          incorrectly. Now changed to what I think is the correct result. 8 Nov 2011. DWF.
      Added the ability to send the output directly to a file via the OUTPUT keyword. 9 Dec 2011, DWF.
      PostScript, PDF, and Imagemagick parameters can now be tailored with cgWindow_SetDefs. 14 Dec 2001. DWF.
      I had a problem with OVERPLOTs being slightly offset because I was calculating the xrange
          and yrange, rather than taking them from !X.CRange and !Y.CRange. 17 Dec 2011. DWF.
      Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
      Incomplete implementation of new color selection scheme, fixed. 30 Dec 2011. DWF.
      The change of 17 Dec 2011 was incorrect, as I misunderstood the problem. Restored original. 30 Dec 2011. DWF.
      Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF.
      Added a SMOOTH keyword. 26 April 2012. DWF.
      Small fix (CR missing!) to allow overplotting in cgWindow. 26 April 2012. DWF.
      The Outline keyword was incorrectly drawing the last histogram bin outline. Fixed. 26 April 2012. DWF.
      Added POSITION and PROBTHICK keywords to set the plot position and the thickness of the cumulative
          probability line, respectively. 25 May 2012. DWF.
      If the cumulative probability option (keyword OPROBABILITY) is set, a second axis is drawn indicating
          the cumulative probablity from 0 to 1. 25 May 2012. DWF.
        Whoops! Don't want to set default position unless Total(!P.MULTI) equals zero. 25 May 2012. DWF.
        More work on getting the cumulative probability to be correctly plotted. 30 May 2012. DWF.
        More whoops! Setting POSITION now interfering with LAYOUT keyword. More fixes to restore LAYOUT. 26 July 2012. DWF.
        Aaauuughhh! Typo introduced in yesterday's fix before I saved final version. 27 July 2012. DWF.
        Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
        Mis-spelled "probability" in one section of the code. Fixed. 31 July 2012. DWF.


    Copyright (c) 2007-2012, Fanning Software Consulting, Inc.

© 2020 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us