coyote: CGTAYLORDIAGRAM

Description
The program implements a Taylor Diagram in IDL direct graphics. Addtional information can be found
`in this article `.
.. image:: cgtaylordiagram.png
From the 2001 IPCC Reoprt::
      "Taylor diagrams provide a way of graphically summarizing how closely 
      a pattern (or a set of patterns) matches observations.  The similarity between two 
      patterns is quantified in terms of their correlation, their centered root-mean-square 
      difference and the amplitude of their variations (represented by their standard 
      deviations).  These diagrams are especially useful in evaluating multiple aspects of 
      complex models or in gauging the relative skill of many different models."
      "In general, the Taylor diagram characterizes the statistical relationship between two 
      fields, a "test" field (often representing a field simulated by a model) and a 
      "reference" field (usually representing “truth”, based on observations)."
      "The two-dimensional space of the Taylor diagram can represent three different statistics 
      simultaneously::
         - The centered RMS difference, 
         - The correlation, 
         - The standard deviation
The reference to Karl Taylor's original paper explaining the diagram is Taylor, K.E., 
`Summarizing multiple aspects of model performance in a single diagram, ` J. Geophys. Res., 106, 7183-7192, 2001.
Here is a `simple, but complete, explanation ` of the diagram.      
Categories
Graphics
Params
correlation: in, required, type=float
    An array of correlation coefficients for the points that will be plotted on the diagram.
    This array must be the same length as the `stddev` array and the `Labels` array, if it is used.
stddev: in, required, type=float
    An array of standard deviations for the points that will be plotted on the diagram.
    This array must be the same length as the `correlation` array and the `Labels` array, if it is used.
Keywords
addcmd: in, optional, type=boolean, default=0
    Set this keyword to add the command to the resizeable graphics window cgWindow.
c_correlation: in, optional, type=string, default="grn7"
    The name of the color used for the correlation lines on the diagram.
c_stddev: in, optional, type=string, default="blu7"
    The name of the color used for the standard deviation lines on the diagram.
c_ref: in, optional, type=string, default="pur7"
    The name of the color used for the observed reference line on the diagram.
c_symbol: in, optional, type=string, default="red"
    The name of the color used for the point symbols on the diagram.
labels: in, optional, type=string
    An array of string labels for the points that will be plotted on the diagram.
    This array must be the same length as the `stddev` array and the `correlation` array.
noerase: in, optional, type=boolean, default=0
    Set this keyword if you don't want the Taylor Diagram plot to erase what is already on
    the display.
output: in, optional, type=string
    The name of an output file to write the Taylor Diagram to. The type of file is taken from
    the file extension. For example, OUTPUT='mydiagram.png'. It is assumed that Ghostscript and
    ImageMagick have been installed properly for all raster file output. If the Output keyword is
    used, nothing is drawn on the display. This keyword cannot be used with the Overplot keyword.
overplot: in, optional, type=boolean, default=0
    Set this keyword to overplot onto an already existing Taylor Diagram. Many keywords are
    ignored if this keyword is set. Only the data is drawn. The Output keyword cannot be used
    if overplotting.
position: in, optional, type=float
    A four-element, normalized array giving the position of the plot in the display window: [x0,y0,x1,y1].
ref_stddev: in, optional, type=float, default=1.0
    The reference standard deviation. This is typically the "observed" or "model" value. A scalar.
rms_circles_off: in, optional, type=boolean, default=0
    Set this keyword to prevent the drawing of the RMS circles that radiate out from the observed RMS value.
rms_format: in, optional, type=string, default='(I0)'
    Set this keyword to a format string that is used for format the RMS circle labels.
rms_increment: in, optional, type=float, default=1.0
    The RMS circles are drawn from the observed RMS value, using this value as an increment of the circle radius.
rms_labels_off: in, optional, type=boolean, default=0
    Set this keyword to prevent the drawing of the RMS circle labels. If this keyword is set, only the RMS
    circles are drawn.
stddev_max: in, optional, type=float
    The maximum standard deviation to plot on the graph. 
symbol: in, optional, type=integer, default=16
    The symbol used for the data points on the diagram. Any symbol supported by `cgSymCat`.
symsize: in, optional, type=float, default=1.5
    The size of the symbol used for the data points on the diagram.
window: in, optional, type=boolean, default=0
    Set this keyword to replace all the commands in a current cgWindow or to
    create a new cgWindow for displaying this command.
Examples
Here is how to use this program::
  labels = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H']            ; Point labels.
  stddev = [1.4, 0.9, 1.0, 1.272, 1.1, 0.95, 1.08, 0.5]        ; Standard Deviations
  correlation = [0.8, 0.9, 0.65, 0.74, 0.91, 0.98, 0.85, 0.35] ; Correlations
  ref_std = 1.0                                                ; Reference standard (observed)
  stddev_max = 1.5                                             ; Standard Deviation maximum
  cgTaylorDiagram, stddev, correlation, REF_STDDEV=ref_std, STDDEV_MAX=stddev_max, LABELS=labels
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, 10 January 2013 by David W. Fanning from a program by Fernando Santoro of
       ExelisVis that I found in the IDL Code Repository on the ExelisVis web page.
       Fernando did *all* of the hard work writing the program for the IDL 8 function
       graphics routine. I simply copied most of his code and adapted it for non-IDL 8 
       users. I also added a couple of features I though were missing from the original code.
   Added OVERPLOT keyword. 21 May 2013. DWF.
   Added RMS_*** keywords to allow more control over the drawing and labeling of the RMS circles 
       on the plot. 29 July 2013. DWF.
   Modified the algorithm that places the "Correlation" label to allow multiple plots in a 
      window. Also removed a cgPolyFill command that appeared to have no effect. 19 Nov 2013. DWF.
   Added NOERASE keyword and made sure no window was opened when OUTPUT keyword is used. 21 Nov 2013. DWF.
   Added check to not create initial plot if PostScript is the current device. 18 Feb 2015. DWF.
   Small modification to prevent extraneous drawing on right edge of plot in PostScript files,
      and updated figures and documentation. 10 April 2015. DWF.
   Another small modification to accommodate extraneous line removal when doing multiple plots on
      a page. Appears to work in both PostScript and on the display for multiple plots. 19 May 2015. DWF.
Copyright
Copyright (c) 2013-2015, Fanning Software Consulting, Inc.