# coyote: CGSCATTER2D

- [Source code]

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 <http://www.idlcoyote.com/documents/programs.php>`
      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.
          Corrected a problem with axis ranges when drawing the first plot in a PostScript file. The problem was that the
              Plot command there was not identical to the other Plot commands in the program and it needs to be
              to get the spacing and axis notation correct. 7 January 2016. DWF.

Copyright

      Copyright (c) 2012-2014, Fanning Software Consulting, Inc.