Contents

graphs

Keywords: plotting

The basic plotting commands are as follows:
  plot(x,y)                   Plot of columns of y against x
  lineplot(x,y)               Connected line plot of columns of y
                              against x
  chplot(x,y,symbols:ch)      Plot of columns of y against x using
                              symbols specified by ch
  stringplot(x,y,strings:s)   Draw labeling information in s at
                              positions defined by x and y
  boxplot(x1,x2,...,xk)       Box plots of vectors x1, ..., xk
  boxplot(structure(x1,...xk))
  addpoints(x,y)              Add data to an existing graph
  addlines(x,y)               Add line connected data to an existing
                              graph
  addchars(x,y,symbols:ch)    Add data to an existing graph using
                              symbols specified by ch
  addstrings(x,y,strings:s)   Add labeling information in s at coord-
                              inates in x and y in an existing graph
  showplot()                  Redisplay previously displayed graph

Arguments x and y can be replaced by a structure with at least two
components which are interpreted as x and y.  Any additional components
are ignored.  For example, plot(x,y) and plot(structure(x,y,z)) are
equivalent.

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

Except for stringplot() and addstrings(), any points or lines outside
the border of the plot are omitted.  The exception for stringplot() and
addstrings() allows you to place custom labels outside the frame of the
graph.

You can also draw a graph by a command like
  Cmd> GRAPHWINDOWS[1] <- structure(x:height,y:weight [,...])
where any additional arguments are graphics keyword phrases.  See topics
'graph_assign' and 'GRAPHWINDOWS' for details.

See topic 'graph_keys' for information on optional graphics keyword
phrases.  You can use some of these to specify axis labels and a title
or plotting limits.  Examples are xmin:0, xmax:10,ymin:-1, ymax:1,
xlab:"X axis label", ylab:"Y axis label", and title:"Title above graph".
You can use others to specify whether the graph is to be displayed,
written to a file, or be saved in the form of a GRAPH variable.  Using
keyword 'keys', you can specify such keyword information as components
of a structure.

See topic 'graph_files' for information on how to save a plot in a file
using keywords 'file', 'new, 'ps', 'screendump', and 'epsf'.

See topic 'graph_ticks' for information on using keywords 'ticks',
'xticks', 'yticks', 'xticklen', 'yticklen', 'xticklabs' and 'yticklabs'
to modify default tick mark placement and labeling.

See topic 'graph_border' for information on using keyword 'borders' to
control which borders will be drawn

In windowed versions you can use the mouse in a graphics window to
specify the positions of points, lines or rectangles to be drawn into
the graph.  You can do the same, with some restrictions, in the
Unix/Linux version using Tektronix emulation with an emulator that
implements graphical input mode.  See Mouse().

                      Logarithmic scaling of axes
Keyword phrases 'logx:T' and/or 'logy:T' specify that logarithmic
scaling is to be used for the corresponding axis.  When plotted, the
values are transformed to logarithms, but tick marks are still in the
original units.  For example, plot(x,y,logy:T) creates a semi-log plot,
with a linear x-axis and a logarithmic y-axis and plot(x,y,logx:T,
logy:T) creates a log-log plot.

With logx:T, any data points with x <= 0 are treated as if they had
MISSING values as are data points with y <= 0 when you use logy:T.  A
warning message is given.

                     Low resolution ("dumb") plots
By default, all plotting commands produce high resolution graphs.
Keyword phrase 'dumb:T' on any plotting command directs that the graph
should be "dumb", that is a low resolution plot using characters that
can be printed on any printer.  If you prefer to have dumb plots as the
default, type setoptions(dumbplot:T); 'dumb:F' will then be necessary to
get high resolution plots.  The default size of a dumb plot, including
labels, is M lines by N - 1 character positions, where M and N are the
values of options 'height' and 'width'.  You can override these defaults
by graphics keywords 'height' and 'width' whose values define M and/or
N.  See topics setoptions(), 'options' and 'graph_keys'.

                  Specification of data to be plotted
Commands plot(), chplot(), lineplot(), stringplot(), addpoints(),
addlines(), addchars() and addstrings() all require arguments x and y
which specify plotting positions.  x is a REAL vector and y is a REAL
vector or matrix.  If y has more than 1 column, each column is plotted
against x.  For addstrings(), y must be a vector of the same length as
x.

Alternatively, arguments x and y can be replaced by a structure with at
least two REAL components.  For example, plot(structure(x,y)) is
equivalent to plot(x,y).  If there are more than two components, the
additional ones are ignored.  For example, plot(structure(x,y,
info:"Test Data")) is also equivalent to plot(x,y).

Except for stringplot() and addstrings(), x can be a scalar or a vector
of length 2 which implicitly specifies ny equally spaced values where ny
= nrows(y).  When x = x0 is a scalar x0, the implied vector is
vector(x0,x0+1,x0+2,...).  If x is vector(x0,dx), the implied vector is
vector(x0,x0+dx,x0+2*dx, ...).  Otherwise, x and y must have the same
number of rows.

For plot(), chplot(), and lineplot(), if x or y are specified as keyword
phrases, as in plot(Time:tm,Level:y), the keywords are used as axis
labels; however, keywords 'xlab' or 'ylab' (see below) will override the
name:x or name:y forms.  See topic 'graph_keys'.

Examples:
   plot(1,y) is short for plot(run(nrows(y)),y)
   plot(vector(1979,1/12),y) is short for
              plot(run(0,nrows(y)-1)/12+1979,y)
The second example might be used to plot monthly data starting January
1979 against time.

                        GRAPH variable LASTPLOT
As a "side effect", all plotting commands create a GRAPH variable with
name LASTPLOT which encapulates all the information used to create the
plot.  The information is saved in a resolution independent form.  You
can assign LASTPLOT to another variable (for example, plot1 <- LASTPLOT)
or redisplay it, possibly with changed limits or labeling information,
using showplot().  You can print it (as a "dumb" plot) by
print(LASTPLOT) or write(LASTPLOT) or simply by typing LASTPLOT.

You can suppress the creation of LASTPLOT by keyword phrase 'keep:F'.
This might be useful if you were running out of memory.


In addition, MacAnova maintains GRAPHWINDOWS, a special structure
variable, with one component for each possible graphics window (1
component in non-windowed versions).  Briefly, GRAPHWINDOWS[I]
(component I of GRAPHWINDOWS) is either a GRAPH variable encapsulating
the plot in graphics window I, or is NULL when there is no plot in
graphics window I.  See topic 'GRAPHWINDOWS'.

                       Adding information to a plot
Commands addpoints(), addchars(), addlines(), and addstrings() allow you
to display GRAPH variables with added information.  Alternatively and
equivalently, you can use the keyword phrase 'add:T' as an argument to
plot(), chplot(), lineplot() or stringplot().  If the first argument is
a GRAPH variable (for example, addlines(graph,x,y)), the plot combines
the information in the GRAPH variable with the new information provided.
Otherwise, the information in LASTPLOT is used.  In no case is any GRAPH
variable other than LASTPLOT changed.

If graph is a GRAPH variable, plot(graph,x,y), chplot(graph,x,y,
symbols:c) and lineplot(graph,x,y) are equivalent to addpoints(graph,
x,y), addchars(graph,x,y,symbols:c) and addlines(graph,x,y),
respectively.

To force recomputation of any of xmin, xmax, ymin or ymax to include all
data use keyword phrases xmin:?, xmax:?, ymin:?, or ymax:?.

To suppress immediate display of the graph, as when you are building a
complex graph in stages, use 'show:F' as an argument to each plotting
command.  When you are done, simply type showplot().  It is an error to
use both 'show:F' and 'keep:F'.

Examples:
  Cmd> plot(x,y,show:F); graphVar <- LASTPLOT
  Cmd> addpoints(3,4)  # or plot(3,4,add:T) or plot(LASTPLOT,3,4)
  Cmd> addpoints(graphVar,10,20,keep:F)#or plot(graphVar,10,20,keep:F)
  Cmd> showplot(xmin:0,xmax:0,ymin:0,ymax:0)
produces three plots.  The first and third are plots of y vs x with the
addition of a single point at x=3 and y=4, and the second is a plot of y
vs x with the addition of a point at x = 10 and y = 20.  MacAnova also
recomputes the extremes displayed for the third plot.  Because of
'keep:F' LASTPLOT is not updated after the second addpoints() command.

                             Graph Windows
On versions with windows (Macintosh, Windows and Motif), up to eight
windows are available for use by plotting commands.  In addition, on a
Macintosh, "Panel of Graphs" windows, containing miniature replicas of
up to four plots in their four corners are also created.

The graph in the currently displayed window, including the panel
windows, may be saved to the Clipboard (not in Motif version) by
selecting Copy from the Edit menu, saved to a file by selecting Save
Graph As... on the File menu (Macintosh only) or printed by selecting
Print... on the File menu.

On any plotting command you can specify which window to draw in by
keyword phrase 'window:n', where 1 <= n <= 8.  Keyword phrase 'window:0'
means you want to reuse the most recently drawn window.  This is the
default on any plotting command adding information to a previous plot.
This is useful for displaying a sequence of related plots that differ in
the value of a parameter.  If 'window:n' is not used and a plot is not
being added to, the first unused window is selected, or if all windows
are in use, a message is printed.

                         Pausing between plots
Keyword phrase 'pause:T' on any plotting command results in MacAnova
pausing after the plot is drawn.  This is particularly useful when
drawing repeated graphs in a 'for' or 'while' loop.  Keyword phrase
'pause:F' suppresses any such pause.  The default on windowed versions
is pause:F while under DOS or Unix/Linux it's pause:T.  On all machines,
the pause can be terminated by hitting RETURN.  On the Macintosh, any
non-command key terminates the pause, and you can use the File and Edit
menus to print the graph or to Copy the graph to the Clipboard.
Together with the window keyword, this permits you to display an
unlimited number of graphs successively in the same window, pausing
after each one to examine it and possibly print it or copy it.

                         Plotting on Unix/Linux
Except for the Motif version, on Unix/Linux computers, plotting commands
produce Tektronix compatible plotting sequences.  If MacAnova is running
in a Xterm pseudo VT100 window on a workstation, a pseudo Tektronix 4014
graphics window is opened and drawn to, switching back to the VT100
window when done.

The CHARACTER strings which make up the value of option 'tekset' (see
subtopic 'options:"tekset"') are sent to the terminal to switch into and
out of Tektronix emulation mode.  MacAnova initializes the value of
'tekset' for Xterm, when that is appropriate.  Otherwise, the value of
'tekset' is intialized with strings that are recognized by Versaterm, a
Macintosh terminal emulator program.  When you are using some other
terminal emulator (such as DOS kermit or Macintosh NCSA Telnet) that
supports Tektronix 4014 plotting, you will need to set option 'tekset'
appropriately.  Some suggested values are given in topic 'options'.  See
also topics vt() and tek().