idlastro / Math and Statistics: PLOTHIST

[Source code]

NAME
PLOTHIST
PURPOSE
Plot the histogram of an array with the corresponding abscissa.
CALLING SEQUENCE
plothist, arr, xhist, yhist, [, BIN=, /FILL, /NOPLOT, /OVERPLOT, PEAK=,
                               /AUTOBIN,  ...plotting keywords]
INPUTS
arr - The array to plot the histogram of.   It can include negative
      values, but non-integral values will be truncated.              
OPTIONAL OUTPUTS
xhist - X vector used in making the plot  
        ( = lindgen( N_elements(h)) * bin + min(arr) )
yhist - Y vector used in making the plot  (= histogram(arr/bin))
OPTIONAL INPUT-OUTPUT KEYWORD
BIN -  The size of each bin of the histogram, scalar (not necessarily
       integral).  If not present (or zero), then the default is to 
       automatically determine the binning size as the square root of 
       the number of samples
       If undefined on input, then upon return BIN will contain the 
       automatically computing bin factor.
OPTIONAL INPUT KEYWORDS
/AUTOBIN - (OBSOLETE) Formerly would automatically determines bin size 
           of the histogram as the square root of the number of samples. 
           This is now the default so the keyword is no longer needed.
           Use the  BIN keyword to manually set the bin size.
AXISCOLOR - Color (string or number) of the plotting axes.  
BOXPLOT - If set (default), then each histogram data value is plotted
       "box style" with vertical lines drawn from Y=0 at each end of 
        the bin width.   Set BOXPLOT=0 to suppress this.
COLOR - Color (number or string) of the plotted data.    See CGCOLOR
        for a list of available color names. 
/HALFBIN - Set this keyword to a nonzero value to shift the binning by
        half a bin size.     This is useful for integer data, where e.g.
        the bin for values of 6 will go from 5.5 to 6.5.   The default
        is to set the HALFBIN keyword for integer data, and not for
        non-integer data.     
/NAN - If set, then check for the occurence of IEEE not-a-number values
       This is the default for floating point or Double data
/NOPLOT - If set, will not plot the result.  Useful if intention is to
       only get the xhist and yhist outputs.
/OVERPLOT - If set, will overplot the data on the current plot.  User
      must take care that only keywords valid for OPLOT are used.
PEAK - if non-zero, then the entire histogram is normalized to have
       a maximum value equal to the value in PEAK.  If PEAK is
       negative, the histogram is inverted.
/FILL - if set, will plot a filled (rather than line) histogram.
/ROTATE - if set, the plot is rotated onto it's side, meaning the bars 
       extend from left to right.  Xaxis corresponds to the count within 
       in each bin.      Useful for placing a histogram plot
       at the side of a scatter plot.
 WINDOW - Set this keyword to plot to a resizeable graphics window
The following keywords will automatically set the FILL keyword
FCOLOR - color (string or number) to use for filling the histogram
/FLINE - if set, will use lines rather than solid color for fill (see
        the LINE_FILL keyword in the POLYFILL routine)
FORIENTATION - angle of lines for fill (see the ORIENTATION keyword
        in the POLYFILL routine)
FPATTERN - the pattern to use for the fill (see the PATTERN keyword
        in the POLYFILL routine)
FSPACING - the spacing of the lines to use in the fill (see the SPACING
        keyword in the POLYFILL routine)
FTHICK - the thickness of the lines to use in the fill (see the THICK
        keyword in the POLYFILL routine)
Any input keyword that can be supplied to the cgPLOT procedure (e.g. XRANGE,
AXISCOLOR, LINESTYLE, /XLOG, /YLOG) can also be supplied to PLOTHIST.
EXAMPLE
(1) Create a vector of random 1000 values derived from a Gaussian of 
mean 0, and sigma of 1.    Plot the histogram of these values with a 
binsize of 0.1, and use a blue colored box fill.
IDL> a = randomn(seed,1000)
IDL> plothist,a, bin = 0.1,fcolor='blue'
(2) As before, but use autobinning and fill the plot with diagonal lines at 
    a 45 degree angle
IDL> plothist,a, /fline, forient=45
NOTES
David Fanning has written a similar program CGHISTOPLOT with more graphics
options:   See http://www.idlcoyote.com/programs/cghistoplot.pro
MODIFICATION HISTORY
Written     W. Landsman            January, 1991
Add inherited keywords W. Landsman        March, 1994
Use ROUND instead of NINT  W. Landsman   August, 1995
Add NoPlot and Overplot keywords.   J.Wm.Parker  July, 1997
Add Peak keyword.   J.Wm.Parker  Jan, 1998
Add FILL,FCOLOR,FLINE,FPATTERN,FSPACING keywords. J.Wm.Parker Jan, 1998
Add /NAN keyword        W. Landsman October 2001
Don't plot out of range with /FILL, added HALFBIN keyword, make
half bin shift default for integer only W. Landsman/J. Kurk May 2002
Add BOXPLOT keyword, use exact XRANGE as default W.L.  May 2006
Allow use of /XLOG and /YLOG keywords  W.L. June 2006
Adjust Ymin when /YLOG is used  W. L.  Sep 2007
Added AXISCOLOR keyword, fix color problem with overplots WL Nov 2007
Check when /NAN is used and all elements are NAN  S. Koposov Sep 2008
Added /ROTATE keyword to turn plot on its side. J. Mullaney, 2009.
Added FTHICK keyword for thickness of fill lines. L. Anderson Oct. 2010
Use Coyote Graphics  W. Landsman Feb 2011
Explicit XSTYLE, YSTYLE keywords to avoid _EXTRA confusion WL. Aug 2011
Fix PLOT keyword problem with /ROTATE  WL  Dec 2011
Fix problems when /XLOG is set A. Kimball/WL April 2013
Fix FILL to work when axis is inverted (xcrange[0] >
  xcrange[1]) T.Ellsworth-Bowers July 2014
Make /NaN,/AUTOBIN and BOXPLOT the default  W. Landsman   April 2016
Speed up COLOR processing W. Landsman  July 2016