idlastro / Math and Statistics: PLOTERROR

[Source code]

NAME
PLOTERROR
PURPOSE
Plot data points with accompanying X or Y error bars.
EXPLANATION
This is a greatly enhanced version of the standard IDL Library routine
PLOTERR
Note that since December 2013 a similar error plotting capablity is 
available in CGPLOT (http://www.idlcoyote.com/programs/cgplot.pro).
CALLING SEQUENCE
ploterror, [ x,]  y, [xerr], yerr [, TYPE=, /NOHAT, HATLENGTH= , NSUM =
             ERRTHICK=, ERRSTYLE=, ErrcolOR=, NSKIP=, .. PLOT keywords]
INPUTS
X = array of abscissas.
Y = array of Y values.
XERR = array of error bar values (along X)
YERR = array of error bar values (along Y)
OPTIONAL INPUT KEYWORD PARAMETERS
TYPE = type of plot produced.  The possible types are:
         TYPE = 0 :       X Linear - Y Linear  (default)
         TYPE = 1 :       X Linear - Y Log
         TYPE = 2 :       X Log    - Y Linear
         TYPE = 3 :       X Log    - Y Log
         Actually, if 0 is specified, the XLOG and YLOG keywords
         are used.  If these aren't specified, then a linear-linear
         plot is produced.  This keyword is available to maintain
         compatibility with the previous version of PLOTERROR.
/NOHAT     = if specified and non-zero, the error bars are drawn
         without hats.
HATLENGTH = the length of the hat lines in device units used to cap the 
         error bars.   Defaults to !D.X_VSIZE / 100).
ERRTHICK  = the thickness of the error bar lines.  Defaults to the
         THICK plotting keyword.
ERRSTYLE  = the line style to use when drawing the error bars.  Uses
         the same codes as LINESTYLE.
ERRCOLOR =  String (e.g. 'red') or scalar integer (0 - !D.N_TABLE)
         specifying the color to use for the error bars.   See CGCOLOR()
         for a list of possible color names.  See 
         http://www.idlcoyote.com/cg_tips/legcolor.php
         for a warning about the use of indexed color
NSKIP = Integer specifying the error bars to be plotted.   For example,
         if NSKIP = 2 then every other error bar is plotted; if NSKIP=3
         then every third error bar is plotted.   Default is to plot
         every error bar (NSKIP = 1)
NSUM =  Number of points to average over before plotting, default=!P.NSUM
        The errors are also averaged, and then divided by sqrt(NSUM).   
        This  approximation is meaningful only when the neighboring error
        bars have similar sizes.    PLOTERROR does not pass the NSUM 
        keyword to the PLOT command, but rather computes the binning 
        itself using the  FREBIN function.
TRADITIONAL - If set to 0 then a black plot is drawn on a white background
        in the graphics window.   The default value is 1, giving the
        traditional black background for a graphics window.
WINDOW - Set this keyword to plot to a resizeable graphics window
Any valid keywords to the cgPLOT command (e.g. PSYM, YRANGE, AXISCOLOR  
SYMCOLOR, ASPECT) are also accepted by PLOTERROR via the _EXTRA facility.
RESTRICTIONS
Arrays must not be of type string, and there must be at least 1 point.
If only three parameters are input, they will be taken as X, Y and
YERR respectively.
PLOTERROR cannot be used for asymmetric error bars.   Instead use
OPLOTERROR with the /LOBAR and /HIBAR keywords.
Any data points with NAN values in the X, Y, or error vectors are 
ignored.
EXAMPLE
Suppose one has X and Y vectors with associated errors XERR and YERR
(1) Plot Y vs. X with both X and Y errors and no lines connecting
    the points
           IDL> ploterror, x, y, xerr, yerr, psym=3
(2) Like (1) but plot only the Y errors bars and omits "hats"
           IDL> ploterror, x, y, yerr, psym=3, /NOHAT
WARNING
This an enhanced version of the procedure PLOTERR in the standard IDL
distribution.    It was renamed from PLOTERR to PLOTERROR in June 1998
in the IDL Astronomy Library to avoid conflict with the RSI procedure.
PROCEDURE
A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR
and optionally from X - XERR to X + XERR is written to the output device
PROCEDURE CALLS
cgPlot, cgPlots
FREBIN - used to compute binning if NSUM keyword is present
MODIFICATION HISTORY
William Thompson        Applied Research Corporation  July, 1986
DMS, April, 1989        Modified for Unix
Michael R. Greason      ST Systems
May, 1991               Added most of the plotting keywords, put hats
                          on the error bars.
K. Venkatakrishna       Added option to plot xerr, May, 1992
Michael R. Greason      Corrected handling of reversed axes.  Aug. 1992
W. Landsman             Use _EXTRA keyword                    July 1995
W. Landsman             Plot more than 32767 points           Feb 1996
W. Landsman     Fix Y scaling when only XRANGE supplied       Nov 1996
W. Landsman     Added NSKIP keyword                           Dec 1996
W. Landsman     Use XLOG, YLOG instead of XTYPE, YTYPE        Jan 1998
W. Landsman     Rename to PLOTERROR, OPLOTERROR               Jun 1998
W. Landsman  Better default scaling when NSKIP supplied       Oct 1998 
W. Landsman  Ignore !P.PSYM when drawing error bars           Jan 1999
W. Landsman  Handle NSUM keyword correctly                    Aug 1999
W. Landsman  Fix case of /XLOG but no X error bars            Oct 1999
W. Landsman  Work in the presence of NAN values               Nov 2000
W. Landsman  Improve logic when NSUM or !P.NSUM is set        Jan 2001
W. Landsman  Only draw error bars with in XRANGE (for speed)  Jan 2002
W. Landsman  Fix Jan 2002 update to work with log plots       Jun 2002
W. Landsman  Added _STRICT_EXTRA                              Jul 2005
W. Landsman/D.Nidever Fixed case of logarithmic axes reversed Mar 2009
W. Landsman/S. Koch  Allow input to be a single point         Jan 2010
W. Landsman  Add Coyote Graphics                              Feb 2011
W. Landsman Make keyword name ERRCOLOR instead of ECOLOR 
            Speedup when no ERRCOLOR defined                  Feb 2011
D. Fanning Use PLOTS instead of CGPLOTS for speed             Jan 2012