coyote: CGSCATTER2D

Description
The purpose of cgScatter2d is to create a two-dimensional scatter plot with the 
option of drawing a correlation coefficient on the plot.
The program requires the `Coyote Library `
to be installed on your machine.
Params
x: in, required
   The variable along the X or horizontal dimension.
y: in, required
   The varaiable along the Y or vertical dimension.
Keywords
addcmd: in, optional, type=boolean, default=0
   Set this keyword to add the command to the resizeable graphics window cgWindow.
aspect: in, optional, type=float, default=none
   Set this keyword to a floating point ratio that represents the aspect ratio 
   (ysize/xsize) of the resulting plot. The plot position may change as a result
   of setting this keyword. Note that `Aspect` cannot be used when plotting with
   !P.MULTI.
axiscolor: in, optional, type=string, default='opposite'
   The name of the axis color. May be specified as a color table index number, as well.
axescolor: in, optional, type=string
   Provisions for bad spellers.
background: in, optional, type=string, default='background'
   The name of the background color. May be specified as a color table index number, as well.
charsize: in, optional, type=float, default=cgDefCharSize()
   The character size for axes annotations. Uses cgDefCharSize to select default
   character size, unless !P.Charsize is set, in which case !P.Charsize is always used.
color: in, optional, type=string, default='black'
   The name of the data or symbol color. May be specified as a color table index or color triple, as well.
   May be a vector of the same length as the input data vectors.
coefficient: out, optional, type=double
   The Pearson correlation coefficient of the two data sets. Calculated with the IDL routine CORRELATE.
fcharsize: in, optional, type=float
   The character size of the fit parameters that are written on the plot. This keyword is only
   in effect if the `Fit` keyword is set. The default is the same as `Charsize`.
fcolor: in, optional, type=string, default='red'
   The name of the color for the fitting line though the data
fthick: in, optional, type=integer, default=1
   The thickness of the fitting line.
fillcolor: in, optional, type=string
   If this keyword is set to the name of a color, that color will be used to "fill"
   the area of the plot enclosed by the axes. Unfortunately, at this time, the `FillColor`
   keyword can NOT be used with multiple plots, just single plots.
fit: in, optional, type=boolean, default=1
   If this keyword is set to 1 (the default), a straight line is fit through the data
   with the IDL routine LINFIT. If this keyword is set, the Pearson correlation coeffcient
   and the equation of the fitted line is displayed on the scatter plot, unless the `NoDisplay`
   keyword is set.
font: in, optional, type=integer, default=!P.Font
   The type of font desired for axis annotation.
gcolor: in, optional, type=string, default='gray'
   The name of the grid color. May be specified as a color table index number, as well.
glinestyle: in, optional, type=integer, default=1
   The grid linestyle. Dotted by default. An integer from 0 to 5. See the IDL LineStyle 
   graphics keyword documentation.
grid: in, optional, type=boolean, default=0
   Set this keword to 1 to draw a grid on the plot.
isotropic: in, optional, type=boolean, default=0
   A short-hand way of setting the `Aspect` keyword to 1.
layout: in, optional, type=intarr(3)
   This keyword specifies a grid with a graphics window and determines where the
   graphic should appear. The syntax of LAYOUT is three numbers: [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.
nodisplay, in, optional, type=boolean default=0
   If this keyword is set, then the Pearson correlation coefficient and the equation
   of the fitting line is not displayed on the plot. This keyword is only considered if
   the `Fit` keyword is set.
noerase: in, optional, type=boolean, default=0
   Set this keyword to draw the plot without erasing the display first.
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.
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.
overplot: in, optional, type=boolean, default=0
   Set this keyword if you wish to overplot data on an already exisiting set of
   axes. It is like calling the IDL OPLOT command.
params: out, optional, type=double
   The output line fitting parameters [intercept, slope].
position: in, optional, type=vector
   The usual four-element position vector for the Plot comamnd. Only monitored and
   possibly changed if the `Aspect` keyword is used.
psym: in, optional, type=integer, default=2
   Any normal IDL PSYM values, plus any value supported by the Coyote Library
   routine cgSYMCAT. An integer between 1 and 46.
symsize: in, optional, type=float, default=1.0
   The symbol size.
title: in, optional, type=string, default=""
   The title of the plot.
traditional: in, optional, type=boolean, default=0
   If this keyword is set, the traditional color scheme of a black background for
   graphics windows on the display is used and PostScript files always use a white background.
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.
xrange: in, optional, type=float
   The X range of the plot.
xstyle: in, optional, type=integer, default=0
   The value sent to the XStyle keyword for the Plot command.
xticklen: in, optional, type=float
   The X tick length. Will be set to 1.0 if the `Grid` keyword is set.
xtitle: in, optional, type=string', default=""
   The X title of the plot.
yrange: in, optional, type=float
   The Y range of the plot.
ystyle: in, optional, type=integer, default=0
   The value sent to the YStyle keyword for the Plot command.
yticklen: in, optional, type=float
   THe Y tick length. Will be set to 1.0 if the `Grid` keyword is set.
ytitle: in, optional, type=string', default=""
   The Y title of the plot.
_ref_extra: in, optional, type=any
   Any keyword appropriate for the IDL Plot command is allowed in the program.
Examples
Use to compare two data sets::
   data_1 = cgDemoData(1)+ RandomU(seed, 101) * 10
   data_2 = cgDemoData(1)+ RandomU(seed, 101) * 10
   cgScatter2D, data_1, data_2 
Add a grid to the plot::
   cgScatter2D, data_1, data_2, SymColor='navy', FillColor='rose', /Grid
Output the plot to a PNG file::
   cgScatter2D, data_1, data_2,  SymColor='navy', /Grid, FillColor='rose', Output='scatter.png'
Display the plot in a resizeable graphics window::
   cgScatter2D, data_1, data_2,  SymColor='navy', /Grid, FillColor='rose', /Window
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, 12 January 2012. DWF.
   Removed an extra COLOR keyword and changed an OPLOT command to a PLOTS command
      to allow a vector of colors to be used for the scatter points.
    Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
    Bad logic when creating a GRID and setting [XY]Style keywords. 30 Aug 2013. DWF.
    If you are setting a range, but not using the [XY]Style keywords, then I am going to set [XY]Style=1. 17 Feb 2014. DWF.
Copyright
Copyright (c) 2012-2014, Fanning Software Consulting, Inc.