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