CGSCATTER2D

CGSCATTER2D
The purpose of cgScatter2d is to create a two-dimensional scatter plot with the
option of drawing a correlation coefficient on the plot.

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 PS_END 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.