grace_new

 SYNOPSIS
  Creata a new grace plotting instance

 USAGE
  Struct_Type grace_new ( [args] )

 DESCRIPTION
 This function creates a new instance of a grace plotting object.
 When called with no arguments, it starts up `xmgrace' using the
 `-nosafe' command-line argument.  If a different set of
 arguments are desired, then those may be specified as an array of
 strings.  For example, to start Grace via `xmgrace -fixed -nosafe', use

     g = grace_new (["xmgrace", "-fixed", "-nosafe"]);

 Note that the name of the application to run (`xmgrace' in this
 case) must be the first element in the array.  If the `DISPLAY'
 environment variable is not set, the `gracebat' application will
 be started instead.

 SEE ALSO
  grace.plot, grace.close, grace.save

--------------------------------------------------------------

grace.plot

 SYNOPSIS
  Plot points or lines

 USAGE
  .plot (x [,y [,dy]] [;qualifiers])

 DESCRIPTION
 The `plot' method erases the currently active plot and then
 plots the specified points.  If called with a single argument, that
 argument will be used as the `y' points, and `[1,2,...]'
 will be used as the x points.  If called with 3 arguments, the third
 argument will be used as an error bar.

 QUALIFIERS

   logx[=0|1]            Turn on/off log scaling for the x axis
   logy[=0|1]            Turn on/off log scaling for the y axis
   line=int              Linestyle (0 = no line)
   color=int|str         Line color
   width=float           Line width
   fill=int
   fillcolor=int         Color for the fill region
   fillpat=int           Pattern index for filling
   sym=int               Plot symbol (0 = none)
   symcolor=int|str      Symbol color
   symsize=float         Symbol size (float)
   symfillcolor=int|str  Color used to fill symbols
   symfill=int
   grid[=0|1|2|3]        Draw grid: 0:none, 1:major, 2:minor, 3:major+minor
   dropline              Draw a dropline for each point
   graphtype=str         One of "xy", "xydx", "xydy", "xydxdy", etc..

 The following qualifiers control various attributes of the errorbars:

   errorbar_place=str
   errorbar_color=int|str
   errorbar_pattern=int
   errorbar_linestyle=int
   errorbar_linewidth=float
   errorbar_riser_linewidth=float
   errorbar_riser_linestyle=int
   errorbar_riser_clip_length=float

 Note: Using a negative value for `sym' is equivalent to setting
 `line=0' and `sym=abs(sym)'.

 EXAMPLE

   x = [-10:10:#50];
   y = sin(x);
   g = grace_new ();
   g.plot (x, y ; sym=-4, symfill=2);


 NOTES
 Use the `.get_colors' method to see what colors are available.

 SEE ALSO
  grace_new, grace.oplot, grace.hplot, grace.multi, grace.tick

--------------------------------------------------------------

grace.focus

 SYNOPSIS
  Set the focus to a specified plot

 USAGE
  grace.focus ( [ [nth] | [nrow,ncol] ] )}

 DESCRIPTION
 This method is used to change the focus of the plotting commands
 to a specified graph in a multi-plot situation.  When called without
 arguments, the focus will be changed to the next graph.  When called
 with the single argument `nth', the focus will be set to the
 `nth' plot (`nth=1,2,..').  When called with 2 arguments,
 the first argument specifies the row and the second argument specfies
 the column (`row,col = 1,2,..').

 EXAMPLE

   g = grace_new ();
   g.multi (2, 1; sizes=[3,1]);
   g.focus (1,1);
   g.plot (x,y);
   g.focus (2,1);
   g.plot (x,sin(x*y));


 SEE ALSO
  grace.multi

--------------------------------------------------------------

grace.oplot

 SYNOPSIS
  Overplot points or lines

 USAGE
  .oplot (x [,y [,dy]] [;qualifiers])

 DESCRIPTION
 The `oplot' method may be used to add additional points or lines
 to a plot.  It behaves like `plot' except that it does not erase
 the current plot.  See the `plot' method documentation for
 more details.

 SEE ALSO
  grace.plot, grace.clear

--------------------------------------------------------------

grace.tick

 SYNOPSIS
  Control the axis tick marks

 USAGE
  .tick ([enable_major [,enable_minor]] [;qualifiers])

 DESCRIPTION
 This method may be used to control various aspects of the ticks
 marks.  If called with one argument, the major tics may be turned on
 or off according to whether the argument is non-zero or not.  A
 non-zero value turns on the generation of major ticks, and a value of
 zero turns off their generation.  The optional second parameter
 controls the generation of minor ticks in a similar manner.  Most
 other attributes are controlled by qualifiers.

 QUALIFIERS

  offsetx=int      offset the axis in the x direction by val
  offsety=int      offset the axis in the y direction by val
  majorstyle=int   linestyle for major ticks
  majorwidth=int   line width for major ticks
  majorsize=int    size of the major ticks
  majorcolor=val   color of the major ticks
  minorstyle=int   linestyle for minor ticks
  minorwidth=int   line width for minor ticks
  minorsize=int    size of the minor ticks
  minorcolor=val   color of the minor ticks
  majorgrid=0|1    enable(1) or disable the major grid
  minorgrid=0|1    enable(1) or disable the minor grid


 EXAMPLE

  g = grace_new ();
  g.tick(;minorstyle=2);
  g.plot(x,y;grid=3);


 NOTES
 The tick method operates on both the x and y axes.  Use the
 `xtick' and `ytick' methods for control over the
 corresponding axes.

 The linestyle, width, and color of the major and minor grid lines are
 controlled by the corresponding tick attributes.

 SEE ALSO
  grace.xtick, grace.ytick, grace.plot

--------------------------------------------------------------

grace.label

 SYNOPSIS
  Add a text label to a graph

 USAGE
  .label (string, x, y [;qualifiers])

 DESCRIPTION
 This method may be used to add a text label to the current graph at
 the specfied world coordinate.

 QUALIFIERS

   viewport    Use viewport coordinates instead of world coordinates
   world       Use world coordinates (default)
   rot=angle   Rotate the text by the specified angle
   font=int    Use the specified font
   just=int    justification: left=0, right=1, 2=center
   size=float  Character size to use (default=1)


 NOTES
 It is not a good idea to mix calls to this method with the creation
 of new text strings via the GUI.  As Grace does not permit an
 external program to delete individual strings, the grace module keeps
 an internal table of string ids that have been used.  New strings
 created via the GUI invalidate the table, and there is no way for the
 module to know that this has happened.

 SEE ALSO
  grace.xlabel, grace.title, grace.ylabel

--------------------------------------------------------------

grace.save

 SYNOPSIS
  Save the plot to a file

 USAGE
  .save(filename [;device])

 DESCRIPTION
 This method saves the plot to the specified filename.  Normally
 the file format is determined from the filename extension, e.g.,
 `foo.ps' indicates that `postscript' format is to be used.
 This `device' qualifier may be used to explicitely specify the
 format.

 EXAMPLE

    g.save ("foo.eps");            % Encapsulated Postscript
    g.save ("foo.agr");            % Grace format
    g.save ("foo.out"; device=png);


 SEE ALSO
  grace.close

--------------------------------------------------------------

grace.new_color

 SYNOPSIS
  Add a color to the colormap

 USAGE
  .new_color (name, rgb)

 DESCRIPTION
 The `new_color' method may be used to define a new color name,
 or redefine an existing color.  The `rgb' parameter must be an
 integer that encodes the RGB value to be associated with the name.
 The `id' qualifier may be used to map the color to a specific
 color id value.

 EXAMPLE

   g.new_color ("royalblue", 0x4169E1);
   g.new_color ("royalblue", (65 shl 16)|(105 shl 8)|225);

 The latter example shows how to construct the rgb-encoded integer
 from decimal rgb values.

 SEE ALSO
  grace.plot, grace.get_colors

--------------------------------------------------------------

grace.get_colors

 SYNOPSIS
  Get a list of the color names

 USAGE
  String_Type[] = .get_colors()

 DESCRIPTION
 This method returns an array of the color names that have been
 defined.

 EXAMPLE

   slsh> print (g.get_colors());


 SEE ALSO
  grace.new_color, grace.plot

--------------------------------------------------------------

grace.multi

 SYNOPSIS
  Arrange graphs into a rectangular grid

 USAGE
  .multi(nrows,ncols [;qualifiers]

 DESCRIPTION
 This method may be used to layout graphs onto a rectangular grid
 consisting of `nrows' and `ncols'.  Qualifiers may be used
 to specify the horizontal and vertical separations of the graphs.

 QUALIFIERS

   vgap=value     Controls the vertical spacing between graph windows.
   hgap=value     Controls the horizontal spacing between graph windows.
   offset=value   Sets the distance from the page edges.

 The values for the `vgap' and `hgap' qualifiers appear
 to be fractions of the graph viewport size.  The default values are
 `vgap=0.3' and `hgap=0.3'.  The value of the `offset'
 qualifier appears to a fraction of the page size; the default value
 is 0.15.

 SEE ALSO
  grace.viewport

--------------------------------------------------------------

grace.viewport

 SYNOPSIS
  Set the viewport for the current graph

 USAGE
  .viewport(xmin,xmax,ymin,ymax)

 DESCRIPTION
 This method may be used to set the viewport for the current graph.
 Each of the values must be expressed as a fraction of the longer
 page-size value.  For example, if the page size is 8.5 by 11 inches,
 in portrait mode, then the X viewport coordinate runs from 0 to
 8.5/11=0.773, and the Y coordinate runs from 0 to 1.  The rationale
 behind this stems from the desire to keep the physical size of the
 viewport an invariant with respect to landscape or portrait mode.

 SEE ALSO
  grace.pagesize

--------------------------------------------------------------

grace.pagesize

 SYNOPSIS
  Set the page size

 USAGE
  .pagesize(dx, dy | "letter" | "a4" [;qualifiers])

 DESCRIPTION
 This method may be used to set the size of the plotting page.  The
 value `dx' and `dy' are interpreted as 1/72 of an inch by
 some plot devices, and as pixels by others.  Alternatively, a single
 string such "a4" or "letter" may be used to select the corresponding
 page size.

 After calling this method it is a good idea to re-adjust the
 viewport.  An easy way to do this is to use the `.multi' method.

 QUALIFIERS

    units="cm"|"in"       Interpret dx and dy in the corresponding units
    landscape             Use landscape mode
    portrait              Use portrait mode


 EXAMPLE

    g.pagesize (14, 12 ; units="cm");
    g.multi(1,1);


 SEE ALSO
  grace.viewport, grace.multi

--------------------------------------------------------------

grace.hplot

 SYNOPSIS
  Plot a histogram

 USAGE
  .hplot(x, y [,dy1 [,dy2]] [;qualifiers])

 DESCRIPTION
 This method is typically used to to plot binned data.  In this
 context, `x' is an array that represents the lower bin edges
 and `y' is an array that gives the value of each bin.  If the
 optional third or fourth arguments are present, the corresponding
 error bars (symmetric or asymmetric) will also be plotted.

 QUALIFIERS
  The `hplot' method accepts the same set of qualifiers as the
  the `plot' method.  However, the `sym' qualifier is
  ignored unless error-bars are drawn, in which case the symbol is
  associated with the error bar.

 EXAMPLE

   xbins = [1:1024:8];
   h = hist1d (xbins, pnts);
   g.plot (xbins, h, sqrt(h) ; color="red", sym=2);


 NOTES
 The array `x' that specifies the lower bin edges must be in an
 increasing order such that `x[j+1]>x[j]'.

 SEE ALSO
  grace.plot, grace.ohplot

--------------------------------------------------------------

grace.ohplot

 SYNOPSIS
  Overplot a histogram

 USAGE
  .ohplot()

 DESCRIPTION
  This method may be used to add a histogram plot to a graph.  See
  the `hplot' method for additional information.

 SEE ALSO
  grace.hplot, grace.oplot

--------------------------------------------------------------

grace.xrange

 SYNOPSIS
  Set the world coordinates for the X axis

 USAGE
  .xrange(xmin, xmax)

 DESCRIPTION
  This method may be used to assign world coordinate ranges for the
  `X' axis.  If `xmin' or `xmax' is NULL, the
  corresponding limit will be computed from the data.

 EXAMPLE

   xrange (min(x), max(x));
   xrange (,max(x));          % Set just the upper limit
   xrange (,);                % Turn on autoscaling for this axis


 SEE ALSO
  grace.yrange, grace.world

--------------------------------------------------------------

grace.yrange

 SYNOPSIS
  Set the world coordinates for the Y axis

 USAGE
  .yrange()

 DESCRIPTION
  This method may be used to assign world coordinate ranges for the
  `Y' axis.  If `ymin' or `ymax' is NULL, the
  corresponding limit will be computed from the data.

 EXAMPLE

   xrange (min(y), max(y));
   xrange (,max(y));          % Set just the upper limit
   xrange (,);                % Turn on autoscaling for this axis


 SEE ALSO
  grace.xrange, grace.world

--------------------------------------------------------------

grace.world

 SYNOPSIS
  Set the world coordinates

 USAGE
  .world( [ xmin,xmax,ymin,ymax ])

 DESCRIPTION
  This method may be used to assign world coordinate ranges for the
  `X' and `Y' axes of the current graph.  If any of these
  values is NULL, the corresponding limit will be computed from the
  data (autoscaling).  When called without arguments, all limits will
  be computed from the data.

 SEE ALSO
  grace.xrange, grace.yrange, grace.viewport

--------------------------------------------------------------

grace.ylabel

 SYNOPSIS
  Add the Y-axis label

 USAGE
  .ylabel(string)

 DESCRIPTION
  This method may be used to add a label to the Y axis.

 QUALIFIERS

    color=int|str    Label color
    size=float       Label Size
    font=int         Font id


 SEE ALSO
  grace.xlabel, grace.title, grace.label

--------------------------------------------------------------

grace.xlabel

 SYNOPSIS
  Add the X-axis label

 USAGE
  .xlabel()

 DESCRIPTION
  This method may be used to add a label to the X axis.

 QUALIFIERS

    color=int|str    Label color
    size=float       Label Size
    font=int         Font id


 SEE ALSO
  grace.ylabel, grace.title, grace.label

--------------------------------------------------------------

grace.title

 SYNOPSIS
  Add the title to the graph

 USAGE
  .title(string)

 DESCRIPTION
  This method may be used to add a title to the top of the current
  graph.

 QUALIFIERS

    color=int|str    Label color
    size=float       Label Size
    font=int         Font id


 SEE ALSO
  grace.xlabel, grace.ylabel, grace.subtitle, grace.label

--------------------------------------------------------------

grace.subtitle

 SYNOPSIS
  Add the subtitle to the graph

 USAGE
  .subtitle(string)

 DESCRIPTION
  This method may be used to add a subtitle to the top of the current
  graph under the main graph title.

 QUALIFIERS

    color=int|str    Label color
    size=float       Label Size
    font=int         Font id


 SEE ALSO
  grace.xlabel, grace.ylabel, grace.title, grace.label

--------------------------------------------------------------

grace.redraw

 SYNOPSIS
  Redraw the Grace display

 USAGE
  .redraw()

 DESCRIPTION
  This method is sometimes necessary to tell Grace to redraw or
  refresh display.

 SEE ALSO
  grace.plot

--------------------------------------------------------------

grace.clear

 SYNOPSIS
  Clear the current graph

 USAGE
  .clear()

 DESCRIPTION
  This function may be used to clear the current graph.  Is it not
  normally needed since the `plot' and `hplot' methods
  automatically do this.

 SEE ALSO
  grace.kill, grace.close, grace.plot

--------------------------------------------------------------

grace.close

 SYNOPSIS
  Close the grace session

 USAGE
  .close()

 DESCRIPTION
  This method is used to shutdown the Grace GUI.  Unless this function
  is called, the GUI will remain active even after the S-Lang
  application has exited.

 SEE ALSO
  grace_new, grace.save

--------------------------------------------------------------

grace.kill

 SYNOPSIS
  Delete the current graph

 USAGE
  .kill()

 DESCRIPTION
  This method may be used to delete the current graph.  It can be
  useful in a multi-plot situation when some graphs are not needed.

 SEE ALSO
  grace.clear, grace.close

--------------------------------------------------------------

grace.logx

 SYNOPSIS
  Change the X axis to a log scale

 USAGE
  .logx()

 DESCRIPTION
  This method causes the X axis to use log scaling.  If the
  currently focused graph has a world coordinate
  system that conflicts with log scaling, the world coordinates will
  be changed accordingly (restricted to positive values).

 NOTES
  Normally log scaling is specified when the plot is made via the
  `plot' method's `logx' qualifier.

--------------------------------------------------------------

grace.logy

 SYNOPSIS
  Change the Y axis to a log scale

 USAGE
  .logy()

 DESCRIPTION
  This method causes the Y axis to use log scaling.  If the
  currently focused graph has a world coordinate
  system that conflicts with log scaling, the world coordinates will
  be changed accordingly (restricted to positive values).

 NOTES
  Normally log scaling is specified when the plot is made via the
  `plot' method's `logx' qualifier.

 SEE ALSO
  grace.logx, grace.linx, grace.liny

--------------------------------------------------------------

grace.linx

 SYNOPSIS
  Change the X axis to a linear scale

 USAGE
  .linx()

 DESCRIPTION
  This method may be used to cause the X axis of the current graph to
  use linear scaling.

 SEE ALSO
  grace.liny, grace.logx, grace.logy

--------------------------------------------------------------

grace.liny

 SYNOPSIS
  Change the Y axis to a linear scale

 USAGE
  .liny()

 DESCRIPTION
  This method may be used to cause the Y axis of the current graph to
  use linear scaling.

 SEE ALSO
  grace.linx, grace.logx, grace.logy

--------------------------------------------------------------

grace.legend

 SYNOPSIS
  Add a legend to the current graph

 USAGE
  .legend(x, y, names)

 DESCRIPTION
  This method may be used to add a legend to the graph at the
  coordinate (x,y).  The legend is formed from the `names' array
  and representative lines or symbols used to draw the corresponding
  curves.

 QUALIFIERS
These qualifiers control attribute of the objects in the legend box:

    font=int            Font id
    size=float          character size (default: 1)
    color=int|str       color
    vgap=int
    hgap=int
    length=int

The following qualifiers control the legend box itself:

    loctype=str             "world" or "view"   (default: "world")
    box=0|1                 Turn the box off(0) or on(1)
    box_line=int            Line style
    box_color=int|str       Line color
    box_linewidth=float
    box_pattern=int
    box_fillcolor=int|str
    box_fillpattern=int


 EXAMPLE

   g.plot (x,f(x));
   g.oplot (x,g(x));
   g.legend (2.1, 3.9, ["f(x)", "g(x)"]; box=0);


 SEE ALSO
  grace.label, grace.title, grace.plot

--------------------------------------------------------------

grace.xtick

 SYNOPSIS
  Adjust the X axis ticks

 USAGE
  .xtick()

 DESCRIPTION
  This method may be used to control certain attributes of the X axis
  tick marks.  See the documentation for the `tick' method for
  more information.

 SEE ALSO
  grace.tick, grace.ytick

--------------------------------------------------------------

grace.ytick

 SYNOPSIS
  Adjust the Y axis ticks

 USAGE
  .ytick()

 DESCRIPTION
  This method may be used to control certain attributes of the Y axis
  tick marks.  See the documentation for the `tick' method for
  more information.

 SEE ALSO
  grace.tick, grace.ytick

--------------------------------------------------------------

grace.new_color

 SYNOPSIS
  Define a new color name

 USAGE
  .new_color(name, RGB)

 DESCRIPTION
 This method may be used to add a new named color or redefine a named
 color.  The first parameter is a string that specifies the name of
 the color, and the second is a 3 element integer array whose successive
 elements specify the Red, Green, and Blue content of the color.
 0-255. for the color.

 QUALIFIERS
  id=int     Map the named color to the specified color id or index

 EXAMPLE

   g.new_color("skyblue3", [108, 166, 205]);
   g.plot (x,y; color="skyblue3");


 SEE ALSO
  grace.get_colors, grace.plot

--------------------------------------------------------------
