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 KEYWORDS
/AUTOBIN - Automatically determines bin size of the histogram as the
           square root of the number of samples. Only valid when BIN
           is not set.
AXISCOLOR - Color (string or number) of the plotting axes.  
BIN -  The size of each bin of the histogram,  scalar (not necessarily
       integral).  If not present (or zero), the bin size is set to 1.
/BOXPLOT - If set, then each histogram data value will be plotted
       "box style" with vertical lines drawn from Y=0 at each end of 
        the bin width
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
/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, as shown at the bottom of
         http://www.dur.ac.uk/j.r.mullaney/pages/software.php
 WINDOW - Set this keyword to plot to a resizeable graphics window
The following keywords take effect only if the FILL keyword is set
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 cgcolorfill routine)
FORIENTATION - angle of lines for fill (see the ORIENTATION keyword
        in the cgcolorfill routine)
FPATTERN - the pattern to use for the fill (see the PATTERN keyword
        in the cgcolorfill routine)
FSPACING - the spacing of the lines to use in the fill (see the SPACING
        keyword in the cgcolorfill routine)
FTHICK - the thickness of the lines to use in the fill (see the THICK
        keyword in the cgcolorfill 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 box plotting style.
IDL> a = randomn(seed,1000)
IDL> plothist,a, bin = 0.1, /boxplot
(2) As before, but fill the plot with diagonal lines at a 45 degree 
    angle
IDL> plothist,a, bin=0.1, /fill, /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