# coyote: CGHISTOPLOT

- coyote/Graphics
- [Source code]

Description

      This program is used to draw a histogram plot in an IDL direct graphics window.
      .. image:: cghistoplot.png
      The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
      to be installed on your machine.

Categories

      Graphics

Params

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

Keywords

      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().
      color: in, optional, type=string
         Used as a shorthand way of setting the `DataColorName` keyword or, if the `FillPolygon`
         keyword is set, the `PolyColor` keyword. Only used if those other two keywords are not
         set.
      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`,
         `PATTERN`, `POLYCOLOR`, and `SPACING`.
      line_thick: in, optional, type=integer, default=1
         Set this keyword to set the thickness of lines used in the fill pattern. Applies only
         if the `Line_Fill` keyword is set.
      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.
      ol_style: in, optional, type=integer, default=0
         Set to the index of the line style to use in drawing the histogram boxes.
      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 cgPS_Close 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.)
      peak_height: in, optional
         Set this keyword to the height of the highest peak in the histogram. All other
         peaks will be rendered proportional to this value. Setting this keyword also sets
         the `Frequency` keyword to 0.
      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.)
      subtitle: in, optional, type=string
         The subtitle of the histogram plot.
      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.
      xticknames: in, optional, type=string
          An array of tick names for the axis.
      xtickformat: in, optional, type=string
          As tick format or name of tick formatting function for the axis.
      xticks: in, optional, type=integer
          The number of major tick spaces for the axis.
      xtickvalues: in, optional
          A vector of tick values that should be labelled on the axis.
      xtitle: in, optional, type=string, default="Relative Frequency"
          The X title of the histogram plot.
      yticknames: in, optional, type=string
          An array of tick names for the axis.
      ytickformat: in, optional, type=string
          As tick format or name of tick formatting function for the axis.
      yticks: in, optional, type=integer
          The number of major tick spaces for the axis.
      ytickvalues: in, optional
          A vector of tick values that should be labelled on the axis.
      ytitle: in, optional, type=string, default="Histogram Density"
          The Y title of the histogram plot.
      _ref_extra: in, optional
           Any additional PLOT keywords are passed via keyword inheritance.

Examples

      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::
          http://www.idlcoyote.com/gallery/index.html

Author

      FANNING SOFTWARE CONSULTING::
          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

History

      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.
         Added COLOR keyword. 19 Sept 2012. DWF.
         Now restoring previous plot parameters after drawing cumulative probability axis, so as not
             to interfere with subsequent overplotting. 27 Sept 2012. DWF.
         Changed the way the "ystart" variable is set on log plots. 21 Jan 2013. DWF.
         Now taking into account the MININPUT and MAXINPUT values when calculating a default bin size. 19 Feb 2013. DWF.
         Added [XY]TickNames, [XY]Tickformat, [XY]TickS, and [XY]TickValues keywords. 21 Feb 2013. DWF.
         Now choosing the default tick format of '(F)' when LOG is set. 28 April 2013. DWF.
         Added Line_Thick keyword to change thickness of fill line. 28 Aug 2013. DWF.
         Changed the default background color to "white" from "background" and default axis
             color to "black" from "opposite". It's about time this routine behaved like other
             Coyote Graphic routines! 22 Oct 2013. DWF.
         Fixed problem with XTICKVALUES and YTICKVALUES keywords when plot is rotated. 19 Nov 2013. DWF.
         Added OL_STYLE keyword. 25 Feb 2014. DWF.
         Added Peak_Height keyword. 26 May 2014.

Copyright

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