coyote: CGHISTOPLOT

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 `
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.