Creata a new grace plotting instance
Struct_Type grace_new ( [args] )
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"]);
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.
Plot points or lines
.plot (x [,y [,dy]] [;qualifiers])
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.
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..
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
sym is equivalent to setting
line=0 and sym=abs(sym).
x = [-10:10:#50];
y = sin(x);
g = grace_new ();
g.plot (x, y ; sym=-4, symfill=2);
Use the .get_colors method to see what colors are available.
grace_new,
grace.oplot,
grace.hplot,
grace.multi,
grace.tick
Set the focus to a specified plot
grace.focus ( [ [nth] | [nrow,ncol] ] )}
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,..).
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));
Overplot points or lines
.oplot (x [,y [,dy]] [;qualifiers])
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.
Control the axis tick marks
.tick ([enable_major [,enable_minor]] [;qualifiers])
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.
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
g = grace_new ();
g.tick(;minorstyle=2);
g.plot(x,y;grid=3);
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.
Add a text label to a graph
.label (string, x, y [;qualifiers])
This method may be used to add a text label to the current graph at the specfied world coordinate.
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)
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.
Save the plot to a file
.save(filename [;device])
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.
g.save ("foo.eps"); % Encapsulated Postscript
g.save ("foo.agr"); % Grace format
g.save ("foo.out"; device=png);
Add a color to the colormap
.new_color (name, rgb)
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.
g.new_color ("royalblue", 0x4169E1);
g.new_color ("royalblue", (65 shl 16)|(105 shl 8)|225);
Get a list of the color names
String_Type[] = .get_colors()
This method returns an array of the color names that have been defined.
slsh> print (g.get_colors());
Arrange graphs into a rectangular grid
.multi(nrows,ncols [;qualifiers]
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.
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.
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.
Set the viewport for the current graph
.viewport(xmin,xmax,ymin,ymax)
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.
Set the page size
.pagesize(dx, dy | "letter" | "a4" [;qualifiers])
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.
units="cm"|"in" Interpret dx and dy in the corresponding units
landscape Use landscape mode
portrait Use portrait mode
g.pagesize (14, 12 ; units="cm");
g.multi(1,1);
Plot a histogram
.hplot(x, y [,dy1 [,dy2]] [;qualifiers])
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.
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.
xbins = [1:1024:8];
h = hist1d (xbins, pnts);
g.plot (xbins, h, sqrt(h) ; color="red", sym=2);
The array x that specifies the lower bin edges must be in an
increasing order such that x[j+1]>x[j].
Overplot a histogram
.ohplot()
This method may be used to add a histogram plot to a graph. See
the hplot method for additional information.
Set the world coordinates for the X axis
.xrange(xmin, xmax)
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.
xrange (min(x), max(x));
xrange (,max(x)); % Set just the upper limit
xrange (,); % Turn on autoscaling for this axis
Set the world coordinates for the Y axis
.yrange()
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.
xrange (min(y), max(y));
xrange (,max(y)); % Set just the upper limit
xrange (,); % Turn on autoscaling for this axis
Set the world coordinates
.world( [ xmin,xmax,ymin,ymax ])
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.
Add the Y-axis label
.ylabel(string)
This method may be used to add a label to the Y axis.
color=int|str Label color
size=float Label Size
font=int Font id
Add the X-axis label
.xlabel()
This method may be used to add a label to the X axis.
color=int|str Label color
size=float Label Size
font=int Font id
Add the title to the graph
.title(string)
This method may be used to add a title to the top of the current graph.
color=int|str Label color
size=float Label Size
font=int Font id
Add the subtitle to the graph
.subtitle(string)
This method may be used to add a subtitle to the top of the current graph under the main graph title.
color=int|str Label color
size=float Label Size
font=int Font id
Redraw the Grace display
.redraw()
This method is sometimes necessary to tell Grace to redraw or refresh display.
Clear the current graph
.clear()
This function may be used to clear the current graph. Is it not
normally needed since the plot and hplot methods
automatically do this.
Close the grace session
.close()
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.
Delete the current graph
.kill()
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.
Change the X axis to a log scale
.logx()
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).
Normally log scaling is specified when the plot is made via the
plot method's logx qualifier.
Change the Y axis to a log scale
.logy()
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).
Normally log scaling is specified when the plot is made via the
plot method's logx qualifier.
Change the X axis to a linear scale
.linx()
This method may be used to cause the X axis of the current graph to use linear scaling.
Change the Y axis to a linear scale
.liny()
This method may be used to cause the Y axis of the current graph to use linear scaling.
Add a legend to the current graph
.legend(x, y, names)
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.
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
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
g.plot (x,f(x));
g.oplot (x,g(x));
g.legend (2.1, 3.9, ["f(x)", "g(x)"]; box=0);
Adjust the X axis ticks
.xtick()
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.
Adjust the Y axis ticks
.ytick()
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.
Define a new color name
.new_color(name, RGB)
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.
id=int Map the named color to the specified color id or index
g.new_color("skyblue3", [108, 166, 205]);
g.plot (x,y; color="skyblue3");