/usr/share/doc/gdl-coyote/html/cgplot.html

<html>
<head>
  <TITLE>coyote: CGPLOT</TITLE>
  <style>
dt {font-weight: bold;}
  </style>
</head>
<body>
  <H1><a href="index.html">coyote</a>: CGPLOT</H1>
  <ul>
  <li><a href=Graphics.html>coyote/Graphics</a></li>
    <li><a href="/usr/share/gnudatalanguage/coyote/cgplot.pro">[Source code]</a></li>
  </ul>
  <dl>
<dt>Description</dt>
<dd><pre>
The purpose of cgPlot is to create a wrapper for the traditional IDL graphics
command, Plot. The primary purpose of this is to create plot commands that work
and look identically both on the display and in PostScript files.
Program default colors will depend on the IDL graphics window. If no windows are currently
open when the program is called, cgDisplay is used to create a window.
The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
to be installed on your machine.
</pre></dd>
</dl>

<dl>
<dt>Categories</dt>
<dd><pre>
Graphics
</pre></dd>
</dl>

<dl>
<dt>Params</dt>
<dd><pre>
x: in, required, type=any
     If X is provided without Y, a vector representing the dependent values to be 
     plotted If both X and Y are provided, X is the independent parameter and 
     Y is the dependent parameter to be plotted.
y: in, optional, type=any
     A vector representing the dependent values to be plotted.
</pre></dd>
</dl>

<dl>
<dt>Keywords</dt>
<dd><pre>
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/integer, default='opposite'
   If this keyword is a string, the name of the axis color. 
   Otherwise, the keyword is assumed to be a color index into the current color table.
axescolor: in, optional, type=string/integer
   Provisions for bad spellers.
background: in, optional, type=string/integer, default='background'
   If this keyword is a string, the name of the background color. 
   Otherwise, the keyword is assumed to be a color index into the current color table.
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/integer, default='black'
   If this keyword is a string, the name of the data color. By default, 'black'.
   Color names are those used with cgColor. Otherwise, the keyword is assumed 
   to be a color index into the current color table.
   ERR_COLOR=serr_color, $
err_clip: in, optional, type=boolean, default=0
    Set this keyword to cause error bars to be clipped to the borders of the plot.
    The default is to draw error bars, even if outside the plot.
err_color: in, optional, type=varies
    The color error bars should be drawn in. The default is to use the `Color` keyword.
err_thick:, in, optional, type=integer
    The thickness of the line for drawing the error bars. By default, !P.Thick.
err_width: in, optional, type=float
    The width of the end lines on error bars in normalized coordinates. By default, the
    width is one percent of the width of the axes length in the appropriate dimension.
err_xhigh: in, optional
    The high error values that should be added to the independent or X data values.
err_xlow: in, optional
    The low error values that should be subtracted from the independent or X data values.
err_yhigh: in, optional
    The high error values that should be added to the dependent or Y data values.
err_ylow: in, optional
    The low error values that should be subtracted from the dependent or Y data values.
font: in, optional, type=integer, default=!P.Font
   The type of font desired for axis annotation.
isotropic: in, optional, type=boolean, default=0
   Maintain the same scale on both axes.
label: in, optional, type=string
   A label is similar to a plot title, but it is aligned to the left edge
   of the plot and is written in hardware fonts. Use of the label keyword
   will suppress the plot title.
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.
legends: in, optional, type=object
   One or more cgLegendItem objects that are to be drawn on the plot.
map_object: in, optional, type=object
   If you are drawing on a map projection set up with Map_Proj_Init
   and using projected meter space, rather than lat/lon space, then you can use this
   keyword to provide a cgMap object that will allow you to convert the dependent and independent
   parameters from longitude and latitude values, respectively, to projected meter space
   before drawing. 
nodata: in, optional, type=boolean, default=0
   Set this keyword to draw axes, but no data.
noerase: in, optional, type=boolean, default=0
   Set this keyword to draw the plot without erasing the display first.
oplots: in, optional, type=object
   A single cgOverPlot object, or an array of cgOverPlot objects that will be
   overplot on the axes set up by the original data. The user will be responsible
   for destroying the objects. The cgPlot program will simply draw the objects.
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.
position: in, optional, type=vector
   The usual four-element position vector for the Plot comamnd. Only monitored and
   possibly set if the `Aspect` keyword is used.
psym: in, optional, type=integer
   Any normal IDL PSYM values, plus any value supported by the Coyote Library
   routine cgSYMCAT. An integer between 0 and 46. This may also be set to the
   "name" of a symbol, such as returned from Print, cgSymCat(/Names).
symcolor: in, optional, type=string/integer, default='black'
   If this keyword is a string, the name of the symbol color. By default, 'black'.
   Otherwise, the keyword is assumed to be a color index into the current color table.
symsize: in, optional, type=float, default=1.0
   The symbol size.
title: in, optional, type=string
    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.
xmargin: in, optional
    Set this keyword to a two-element array giving the left and right sides of the plot window
    in units of character size. Use of this keyword is greatly discouraged and is included here
    strictly to make code backward compatable. Use the `Position` keyword instead. This 
    keyword value is only used for the default positioning of a single plot, if no other
    method of specifying the plot position is used.
xrange: in, optional
    Set this keyword to a two-element vector setting the X axis range for the plot.
    If this keyword is used, and the `XStyle` keyword is NOT used, then XSTYLE is set to 1.
xstyle: in, optional, type=integer
    This keyword is a bit map that allows a variety of axis options, depending upon which bit
    is set. Bits are set by adding the following values together when setting the value of
    the keyword::
       Value    Description
         0      Allow axis autoscaling.
         1      Turn axis autoscaling off, force exact axis range.
         2      Extend axis range.
         4      Suppress entire axis.
         8      Suppress box style axis. Draw only main axis.
    To suppress box axis style and force exact axis range, for example, set the keyword to 8+1=9::
        cgPlot, cgDemoData(1), XRange=[15,78], XStyle=9
xtitle: in, optional, type=string
    The X title of the plot.
ymargin: in, optional
    Set this keyword to a two-element array giving the bottom and top sides of the plot window
    in units of character size. Use of this keyword is greatly discouraged and is included here
    strictly to make code backward compatable. Use the `Position` keyword instead. This
    keyword value is only used for the default positioning of a single plot, if no other
    method of specifying the plot position is used.
yrange: in, optional
    Set this keyword to a two-element vector setting the Y axis range for the plot.
    If this keyword is used, and the `YStyle` keyword is NOT used, then YSTYLE is set to 1.
ystyle: in, optional, type=integer
    This keyword is a bit map that allows a variety of axis options, depending upon which bit
    is set. Bits are set by adding the following values together when setting the value of
    the keyword::
       Value    Description
         0      Allow axis autoscaling.
         1      Turn axis autoscaling off, force exact axis range.
         2      Extend axis range.
         4      Suppress entire axis.
         8      Suppress box style axis. Draw only main axis.
        16      Inhibt setting the Y axis minimum value to 0.
    To suppress box axis style and force exact axis range, for example, set the keyword to 8+1=9::
        cgPlot, cgDemoData(1), YRange=[15,28], YStyle=9
ytitle: in, optional, type=string
    The Y title of the plot.
_ref_extra: in, optional, type=any
   Any `IDL Plot keyword <http://www.exelisvis.com/docs/PLOT_Procedure.html>` 
   not defined here is allowed in the program.
</pre></dd>
</dl>

<dl>
<dt>Examples</dt>
<dd><pre>
Use as you would use the IDL PLOT command::
   cgPlot, Findgen(11)
   cgPlot, Findgen(11), Aspect=1.0
   cgPlot, Findgen(11), Color='olive', AxisColor='red', Thick=2
   cgPlot, Findgen(11), Color='blue', SymColor='red', PSym=-16
 Example using error bars::
   data = Congrid(cgDemoData(1), 15)
   seed = -5L
   time = cgScaleVector(Findgen(N_Elements(data)), 1, 9)
   high_yerror = RandomU(seed, N_Elements(data)) * 5 > 0.5
   low_yerror = RandomU(seed, N_Elements(data)) * 4 > 0.25
   high_xerror = RandomU(seed, N_Elements(data)) * 0.75 > 0.1
   low_xerror = RandomU(seed, N_Elements(data))  * 0.75 > 0.1
   xtitle = 'Time'
   ytitle = 'Signal Strength'
   title = 'Error Bar Plot'
   position = [0.125, 0.125, 0.9, 0.925]
   thick = (!D.Name EQ 'PS') ? 3 : 1
   cgDisplay, 600, 500, Title='Errorbar Plot'
   cgPlot, time, data, Color='red5', PSym=-16, $
       SymSize=1.0, Thick=thick, Title=title, XTitle=xtitle, YTitle=ytitle, $
       Position=position, YStyle=1, $
       ERR_XLow=low_xerror, ERR_XHigh=high_xerror, ERR_CLIP=1, $
       ERR_YLow=low_yerror, ERR_YHigh=high_yerror, ERR_Color='blu5'
</pre></dd>
</dl>

<dl>
<dt>Author</dt>
<dd><pre>
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
</pre></dd>
</dl>

<dl>
<dt>History</dt>
<dd><pre>
Change History::
   Written, 12 November 2010. DWF.
   Added SYMCOLOR keyword, and allow all 46 symbols from cgSYMCAT. 15 November 2010. DWF.
   Added NODATA keyword. 15 November 2010. DWF.
   Now setting decomposition state by calling cgSetColorState. 16 November 2010. DWF.
   Final color table restoration skipped in Z-graphics buffer. 17 November 2010. DWF.
   Fixed a problem with overplotting with symbols. 17 November 2010. DWF.
   Background keyword now applies in PostScript file as well. 17 November 2010. DWF.
   Many changes after BACKGROUND changes to get !P.MULTI working again! 18 November 2010. DWF.
   Fixed a small problem with the OVERPLOT keyword. 18 Nov 2010. DWF.
   Changes so that color inputs don't change type. 23 Nov 2010. DWF.
   Added WINDOW keyword to allow graphic to be displayed in a resizable graphics window. 8 Dec 2010. DWF
   Modifications to allow cgPlot to be drop-in replacement for old PLOT commands in 
       indexed color mode. 24 Dec 2010. DWF.
   Previous changes introduced problems with OVERPLOT that have now been fixed. 28 Dec 2010. DWF.
   Set NOERASE keyword from !P.NoErase system variable when appropriate. 28 Dec 2010. DWF.
   Additional problems with NOERASE discovered and solved. 29 Dec 2010. DWF.
   In some cases, I was turning BYTE values to strings without converting to 
       INTEGERS first. 30 Dec 2010. DWF.  
    Selecting character size now with cgDefCharSize. 11 Jan 2011. DWF.   
    Moved setting to decomposed color before color selection process to avoid PostScript
        background problems when passed 24-bit color integers. 12 Jan 2011. DWF. 
    Changed _EXTRA to _REF_EXTRA on procedure definition statement to be able to return
        plot keywords such as XGET_TICKS. 13 Jan 2011. DWF.  
    Added SYMSIZE keyword. 16 Jan 2011. DWF.
    Fixed a problem in which I assumed the background color was a string. 18 Jan 2011. DWF.  
    Added ADDCMD keyword. 26 Jan 2011. DWF.
    Added LAYOUT keyword. 28 Jan 2011. DWF.
    Made a modification that allows THICK and COLOR keywords apply to symbols, too. 24 Feb 2011. DWF.
    Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF
    Somehow I had gotten independent and dependent data reversed in the code. Put right. 16 May 2011. DWF.
    Allowed ASPECT (and /ISOTROPIC) to take into account input POSITION. 15 June 2011. Jeremy Bailin.
    Updated the BACKGROUND color selection from lessons learned in 27 Oct 2011 cgContour 
        corrections. 27 Oct 2011. DWF.
    Added the ability to send the output directly to a file via the OUTPUT keyword. 9 Dec 2011, DWF.
    PostScript, PDF, and Imagemagick parameters can now be tailored with cgWindow_SetDefs. 14 Dec 2011. DWF.
    Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
    Over-zealous use of _STRICT_EXTRA when overplotting resulted in errors. Now use _EXTRA. 1 Jan 2012. DWF.
    Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF.
    Now allowing the user to draw in the "background" color, if the COLOR or AXISCOLOR is "BACKGROUND". 19 March 2012. DWF.
    Scalar input parameters are changed to 1-element vectors to avoid annoying error messages from PLOT. 6 April 2012. DWF.
    Added a LABEL keyword. 12 July 2012. DWF.
    Yikes! Bad choice of variable names in LABEL work yesterday has severe consequences. Changed names. 13 July 2012. DWF.
    Added OPLOTS keyword to allow cgOverplot objects. 18 July 2012. DWF.
    Added the ability to specify a symbol name with the PSYM keyword. 19 Juyl 2012. DWF.
    Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
    Fixed an interaction with the LABEL keyword that prevented a Title from appearing. 2 Oct 2012. DWF.
    Modified the way default colors are selected when the background color is "white". 4 Dec 2012. DWF.
    Still trying to accommodate users who incorrectly specify LONG integers while using INDEXED color. 26 Dec 2012. DWF.
    Modified code that checks to see if COLOR and AXISCOLOR keywords are the same as BACKGROUND and changes them.
         This precludes drawing in background color on non-white backgrounds. Now only change the
         colors if it is possible to draw a background color. 12 Feb 2013. DWF.
    Problem using symbol names (e.g., 'opencircle') in cgWindows is fixed. 10 May 2013. DWF.
    Changed the meaning of ISOTROPIC to its true meaning of keeping the same scale on both axes. 21 June 2013. DWF.
    Added XRANGE, XSTYLE, YRANGE, and YSTYLE keywords. This allows exact axis scaling if the XRANGE or YRANGE
        keywords are used without setting the XSTYLE or YSTYLE keywords, which is more intuitive. 15 July 2013. DWF.
    Added error bar plotting capability via ERR_* keywords. 10 December 2013. DWF.
    Added Map_Object keyword to allow plotting values in longitude/latitude to be converted to XY projected meter
        space automatically. 10 December 2013. DWF.
    Data could sometimes be drawn when OVERPLOT and NODATA keywords were both set. Fixed. 16 Dec 2013. DWF.
    Added ERR_CLIP keyword. 31 Jan 2014. DWF.
    Added a sanity check for inappropriate use of the ISOTROPIC keyword. 6 Feb 2014. DWF.
    Problem with using ISOTROPIC keyword without POSITION keyword fixed. 21 Jun 2014. DWF.
    Fixed incorrect use of MARGIN keyword in cgAspect. 1 Sep 2014. DWF.
    Fixed a problem with plotting with a map coordinate object. I had reversed independent and
         dependent data vectors. 2 Sept 2014. DWF.
    Modified the error bar plotting section of the code to accommodate zoomable plots (eg., cgZPlot). 
         Error bars are drawn only on points inside the axes range. 30 Sep 2014. DWF.
    Further modified error bar plotting to account for possible log axes on the plot. 24 Nov 2014. DWF.
    Added XMargin and YMargin keywords against my better judgement. 15 December 2014. DWF.
    Now taking default values for Title, XTitle, YTitle, XStyle, and YStyle from corresponding
         system variables. 15 December 2014. DWF.
</pre></dd>
</dl>

<dl>
<dt>Copyright</dt>
<dd><pre>
Copyright (c) 2010-2014, Fanning Software Consulting, Inc.
</pre></dd>
</dl>

</body>
</html>
gdl-coyote 2016.11.13-2 / usr / share / doc / gdl-coyote / html / cgplot.html
