Ausam/doc/plot/plot.tut
.po 11
.ll 77
.lt 77
.pl 12i
.hy 0
.nr in 0
.de i0
.in \n(in
..
.de lp
.i0
.ta \\$2
.in \\$1
.ti -\\$2
..
.de s1
.sp 1
.ne 4
..
.de s2
.sp 1
..
.de s3
.sp 1
..
.de fo
'sp 3
'tl ''-%-''
'bp
..
.de th
.de x1
'sp 3
'if o 'tl '\\$1''\\*(HS'
'if e 'tl '\\*(HS''\\$1'
'sp 2
\\..
.wh -8 fo
.wh 0 x1
.in \n(in
..
.de sh
.s1
.ne 5
.ti 0
.cu
\\$1
.sp 2
..
.de bd
.tr __
.ul
\\$1
..
.de bn
.tr __
.ul
\\$1\\t
..
.de it
.tr __
.ul
.li
\\$1
..
.de dt
.ta 8 16 24 32 40 48 56 64
..
.de un
.mc |
..
.de uf
.mc
..
.ds b B
.ds G G
.ds a '
.ds - -
.ds _ _
.ds v |
.ds p J
.ds r
.ds g `
.ds X X
.ds u u
.ds > ->
.ds |
.de EG
.sp
.ne \\$2+1
.nf
.in \\$1
..
.de GE
.in \\$1
.fi
.sp
..
.de BD
\kx\\$1\h'|\nxu+1u'\\$1\h'|\nxu+1u'\\$1
..
.de np
.sp 20u
.ti +4
..
.de dh
.sp
.ul
\\$1\\$2\\$3\\$4\\$5\\$6\\$7:
.br
.in +5
..
.de hd
.in -5
.sp
..
.ds l _\h'-1'<
.tr ~
.th "PLOT"
.ds HS Description
.sh DESCRIPTION
.np
.BD Plot
reads a file of x and y values (the data)
and graphs them on a tektronix terminal or hard copy
plotter.
Plot will select scaling for each axis in order to produce
a reasonable looking graph.
.np
Plot can also accept intructions on how it should draw the graph.
Using these specifications it is possible to:
.EG +10 10
put out a heading on the graph,
label each axis,
plot many lines or sets of data on one graph,
perform a linear regression on the data then show it graphically,
draw different sets of data in different dashed lines and
have each individually labelled,
view any portion of the graph full size.
.GE -10
.sp 1
.np
An example of a graph drawn by
plot
appears below:
.bp
.np
The graph was produced from the following information:
.EG +10 16
legend "COMMUNITY TAX INFORMATION"
comment THESE ARE THE 1977 RESULTS
xaxis "INCOME"
yaxis "RATE OF TAX"
plot x=1 y=2
comment the data came from TEQUS journal
data
1000 0.0
2000 0.0
3000 0.0
4000 5.0
5000 10.0
6000 12.0
7000 15.0
8000 22.1
9000 33.6
.GE -10
The above was entered into a file called "example", then
.EG +10 1
plot example
.GE -10
was typed in as a command to produce the graph shown.
.np
The above example only used some of the available features
of
plot,
but they are
sufficient to produce a neat graph easily.
The features that will produce a tidy
graph are explained below.
.sp 4
.lp +6 5
.BD comment
.li 1
... anything ...
.np
The entire line after the word
comment
is ignored by the program.
It is used to comment about the contents of the
data or about what the
plot
specifications
hope to achieve.
For example:
.EG +10 4
comment this is sundays output
legend "CRIME RATE"
comment IT STARTS AT MIDNIGHT
xaxis "hours"
.GE -10
.lp +6 5
.BD legend
"string"
.np
The string (enclosed in double-quotes ("))
becomes the heading or
legend
of the graph.
It is centred and placed at the top of the
plotting page.
If for example productivity was being plotted
against time,
a heading might be specified by:
.EG +10 1
legend "BUSINESS PRODUCTIVITY"
.GE -10
.lp +6 5
.BD xaxis
"string"
.lp +6 5
.BD yaxis
"string"
.np
These place the strings below the xaxis
and next to the yaxis respectively.
They are used in the same way that
legend
is, and enable the user to explain a feature of
each axis.
As a continuation of the above example,
their usage could be:
.EG +10 2
xaxis "days"
yaxis "Profit ratio"
.GE -10
.lp +6 5
.BD plot
.BD x=
column-n
.BD y=
column-m
.np
The data file may contain many columns of information,
this specification tells the program to use
"column-n" for the x values,
and "column-m" for the y values.
.EG +10 1
plot x=7 y=2
.GE -10
will graph column 7 against column 2.
.np
However, what does the program consider to be a
column of data~?
For example:
.EG +10 7
0 0
1 3
2 5
3 7
4 6
.GE -10
is exactly two columns of information.
In this example, the columns were separated by
spaces, but it is just as legal to separate them by
tabs or commas. Hence:
.EG +10 6
0, 0
1 2
2 ,6
3 5
.GE -10
is still legally two columns, even though there are both commas, tabs
and spaces present.
Plot
does not even require that the columns line up vertically,
thus:
.EG +10 7
0,1,2
3 4 5
6,7 8
9 10 11
30,40 50
.GE -10
is exactly three columns, even though it is messy.
.np
Plot is able to plot out any two columns of data,
and it does not check to see if the other columns are data
at all.
Thus the first and third columns of the following data
can be graphed out legally:
.EG +10 6
1 LINDA 1959
2 RICHARD 1959
3 IAN 1944
4 ADRIAN 1962
.GE -10
by specifying:
.EG +10 1
plot x=1 y=3
.GE
.sp
.lp +6 5
.BD data
.np
This is the final
plot specification.
It states that the instructions to the program
have finished and the data itself begins.
.sp 2
It is now possible to produce
a complete,
labelled graph.
A typical example follows:
.EG +10 11
legend "BUSINESS PRODUCTIVITY"
xaxis "Days"
comment THE UNADJUSTED RATES
yaxis "Profit ratio"
plot x=1 y=3
data
0 30 273.16
1 -10 280.5
2 30 310.99
3 92 323.00
.GE -10
.br
.ne 30
The next example should be entered
and run
if there are any doubts about the above
plot specifications
and their use.
Call the file "example",
and in it place:
.EG +10 16
legend "example plot"
xaxis "TIME"
yaxis "STOCK MARKET ACTIVITY"
plot x=1 y=2
data
1968 0.5
1969 0.6
1970 0.45
1971 0.47
1972 0.56
1973 0.76
1974 0.97
1975 1.1
1976 0.91
1977 0.89
1978 0.68
.GE -10
To graph out the above after it has been entered,
type:
.EG +10 1
plot example
.GE -10
and the program will do the rest.
.ds HS Complete Plot Specifications
.bp
.sh "COMPLETE PLOT SPECIFICATIONS"
.np
The advanced user will find that the basic
plot
specifications
are often insufficient to produce a graph
tailored to his own particular needs,
but the complete specifications
which are given below will give him
full control of all facets of the
graph's appearance.
.np
To make the syntax definitions concise,
abbreviations are used.
The construction "...." literally means
a string in double qoutes. Thus:
.EG +10 2
"THE QUICK BROWN FOX"
"this is how to put "" (double quotes) in"
.GE -10
are correct, but:
.EG +10 2
"under the counter
" GOOD EVENING ""
.GE -10
are not. As shown, a double quote may be
placed in a string by typing in
2 quotes next to each other ("").
An argument placed in square brackets
( [] ) means that it is optional.
.EG +10 1
yaxis ["...."]
.GE -10
states that a string may optionally appear after
the word
yaxis.
.EG +10 1
legend "...." ["...."] [ key at [end][xpos,ypos][quadrant]]
.GE -10
says that one or more strings may appear,
and
key
is optional. Note that
end
and
quadrant
etc, may only be included with key, not by
themselves.
.np
The
plot
specifications
may be entered in free format, but it is suggested
that they be entered in the order shown in this
manual.
Legend, xaxis, yaxis, and date
may only be used once in a graph and hence should
occur first. Strings ("....") may not extend over more than one
line:
.EG +10 2
"THIS IS A LINE OF TEXT ...........
THAT CONTINUES OVER TWO LINES "
.GE -10
is an error.
All reserved words such as
legend,
key,
data,
and
plot
etc are emboldened to show that they
are to be used literally.
.sp 4
.lp +6 5
.BD legend
["...."]["...."][
.BD key
.BD at
[
.BD end
][ xpos,ypos ][ quadrant ]]
.np
Each string (given by "....") becomes a single line of heading
for the graph.
The strings are individually centred,
then placed on their own lines.
.EG +10 1
legend " this is the first line " "this is under"
.GE -10
will produce two lines of heading for the graph.
.np
If three or four sets
of data are to be plotted on the one graph,
then some way of labelling each
line is desirable.
The
key
specification allows this to be done.
Each line has a short description associated
with it called a
.BD keyword.
They identify each set of data. (A
keyword
can be associated with a set of data
by using the
specification
"plot"
(see below)).
.np
When
key
at [ xpos,ypos ][ quadrant ]
is specified, a small box is drawn and the
keywords
are neatly place in it.
They effectively index the lines on the graph.
The position of this box is given by
either an x and y position (0 \*l x \*l 10,
0 \*l y \*l 8 and 0,0 is the bottom left corner), or a
quadrant,
where the
quadrant
is 1, 2, 3, or 4.
Their positions are:
.EG +10 4
1 the top right corner
2 the top left corner
3 the bottom left corner
4 the bottom right corner
.GE -10
Key at end may also be specified.
In this case no box is drawn,
and the
keywords
are placed directly next to where their respective lines end.
For example:
.EG +10 1
legend "HULLO" key at end
.GE -10
will place all
keywords
(whatever they are) at the physical end of the lines.
.dh Defaults
If
.BD key
.BD at
is not specified, then no key-box is
drawn, and the keywords are not used.
.br
If the quadrant or x y position is outside the legal
range then the first quadrant will be used.
.hd
.sp 2
.lp +6 5
.BD xaxis
["...."][
.BD from
min
.BD to
max ][
.BD by
delta ][
.BD at
ypos]
.lp +6 5
.BD yaxis
["...."][
.BD from
min
.BD to
max ][
.BD by
delta ][
.BD at
xpos]
.np
The string is centred and placed next to the
appropriate axis.
The program's automatic
ranging may be overridden, and the distance between the ticks
on each axis may be changed. (Ticks are the small marks on the axes of
a graph to mark its scale).
Normally the program chooses what it considers to be
the best minimum and maximum values for a neat graph.
If the specification:
.EG +10 1
xaxis from 10 to 60 by 5
.GE -10
is used, then the new minimum for the x axis becomes 10,
and the new maximum becomes 60.
The distance between each tick mark becomes 5.
All four parameters may be any real value,
but the best looking graphs are achieved when
the "tick distance" is a well rounded number
such as 1 or 0.5 etc.
The axes are normally drawn at the edge of the graph
so they do not interfere with the data that is being plotted.
The axes (including the numbers on the axes) may be moved
to any position by stating "at" then the
x or y position they are to go to.
.br
.ne 2
For example:
.EG +10 2
xaxis "TIME" at 0
yaxis "RESIDUALS" at 0
.GE -10
will make each axis pass through (0,0)
relative to the data.
.np
Any data points that lie outside the specified
range will not be plotted, and thus any subset
of the data may be viewed.
The specification for the y axis is identical,
except that it operates on the y axis.
Examples of typical usage are:
.EG +10 4
xaxis "time (days)" from 0 to 50
yaxis "DEGREES OF FREEDOM"
.sp
xaxis "ANGLE" by 0.2
yaxis
from -6 to 6 by 1
.GE -10
.ul
.dh Defaults
If
.BD
from
min
.BD to
max is omitted, or
delta is not given then the program selects
a suitable value in each case.
.br
If the positions of the axes are not given
then the x and y axes are placed at the bottom
and the left edges of the graph respectively.
.hd
.lp +6 5
.BD date
["...."]
.np
The current date is normally placed at the top right hand corner
of the graph. This call will use the given string instead of the
date. Thus:
.EG +10 1
date
.GE -10
will suppress the date being printed.
Other examples are:
.EG +10 3
date "SUNDAY"
date "1959/08/24 9:26"
.GE -10
.sp
.lp +6 5
.BD comment
.li 1
...anything...
.np
A comment may be inserted into the
plot specifications,
and all information on the same line
will be totally ignored.
For example:
.EG +10 10
comment This is the stat printout 24/8/1978
legend "PB MARKET RETURNS"
comment anything outside the range given below
comment should not be plotted
xaxis "weeks" from 20 to 70 by 10
yaxis "returns" from -0.5 to 0.5 by 0.1
comment the data came from "SPSS"
data
.li 2
... ...
... ...
.GE -10
.sp
.ne 5
.lp +6 5
.BD plot
[ "...." ][
.BD point=
type ][
.BD line=
type ]
.lp +6 0
[
.BD regression
[ x,y ][ quadrant ]]
.lp +6 0
.BD x=
[ column-n [
.BD *
m ]][ a
.BD to
b ]
.lp +6 0
.BD y=
[ column-n [
.BD *
m ]][ a
.BD to
b ]
.np
The constructions point=type and line=type
tell the program which type of symbol it should
use to plot the data with.
That is, if "line= short" is stated,
then the program will join up the
data points with a short dashed line.
If "point=" is given
instead of "line=", then the data will be plotted
as points (such as crosses), and no line will join them.
If both are stated then the data will be marked as points
and also have a line joining them.
.ti +4
If "regression"
is used then the data will be plotted as points
(crosses are default) and the line of best fit will be drawn in.
The statistics of the line of best fit
may be included with the graph by stating
where they should go, either by x and y position
( 0\*l x \*l10, 0\*l y \*l 8) or
quadrant.
The statistics are :
.EG +10 3
The slope of the line.
The Y intercept.
The goodness of fit or regression co-efficient.
.GE -10
The various options for the of lines and points are:
.EG +7 7
.ul
POINT-TYPE LINE-TYPE
cross solid
dot short
circle short-long
star long
nothing nothing
.GE -7
The type of symbol that is drawn in each case should be obvious,
and if the word "nothing" is stated literally
then no symbol or line is drawn at all.
The user also specifies the column
that contains the x values,
and the column that contains the y's.
For example a simple usage of the column specifier is
.EG +10 1
x= 1
.GE -10
which causes the program to use column
one
for the x values .
Sometimes however, the x values are not properly
scaled, then:
.EG +10 1
x= 1 * 5
.GE -10
would immediately multiply the
first
column by five.
This scaling is the first thing done to the data,
hence all other "plot specifications" operate
after the scaling has been done.
Its most common usage would be to convert a column
of data in one unit of measurement to another.
If a file contained
metres
versus
days,
then:
.EG +10 1
plot x= 1 * 0.001 y= 2 * 24
.GE -10
would convert the graph to
kilometres
versus
hours.
.np
Sometimes one column of data is not present at all,
(perhaps because it was not relevant to program that
generated the data).
.br
.ne 3
So if
.EG +10 2
x= min to max or
y= min to max
.GE -10
is given instead of a number for the column, the program will
generate the data internally between the
minimum and maximum given.
Plot will actually generate a column of data itself
between the specified bounds.
For example:
.EG +10 1
plot x= 1 to 50 y= 1
.GE -10
would be used if the user only had the y values
and wished to generate some x values (between
1 and 50) for it.
.np
The string (in this case a keyword)
is the word or words that become associated with the data.
It tags or identifies the data, so that if a key is wanted
(see
.BD legend),
the program uses the string as an identifying label for that line.
For example:
.EG +10 2
plot "AFTER" x= 1 y= 2
plot "BEFORE" x= 1 y= 3
.GE -10
Other more complete examples are:
.GE +10
plot "line one" line=short point=circle regression 4
x= 1 y= 5
.sp
plot line=short-long x= 1 to 35 y= 4 *10
.sp
.nf
plot "hullo"
line=solid
regression
x= 10*0.01
y= 3*3.5
.fi
plot x= 1 y= 2
.GE -10
.dh Defaults
If a point or line type is omitted then
crosses and solid lines are assumed.
.br
If both the x column and y column is
not given then column one as x values
and column two as y values will be used.
.br
The default scaling factor is one,
ie no scaling.
.br
If no position is given after regression
then the regression statistics are omitted.
.hd
.sp
.lp +6 5
.BD data
[ filename ]
.np
This instruction tells the program where to look for the data points.
If a
filename is given, then the program opens that file and plots the data
points contained in it.
If no name is given, then the data immediately follows.
.br
.ne 3
Valid constructions are:
.EG +10 9
data fred
.sp
data
1.0 1.3
2.0 1.5
3.0 1.6
4.0 2.2
.li 2
... ...
... ...
.GE -10
If
data with no arguments is given, then actual data must follow;
otherwise an error will result.
If the file could not be found or read then the
program will terminate with the appropriate error
message.
.sp 2
.lp +6 5
.BD mark
[[
.BD x=
n ][
.BD y=
m ][
.BD line=
type ]
.np
By using
mark,
the occurance of some event may be marked
on the graph with a horizontal or vertical line.
The vertical line will be placed at position x= n and
a horizontal line placed at position y = m.
These are normally solid lines, but if line=
(then a type)
is given then they are drawn in the appropriate
dashed line. Some possibilities are:
.EG +10 2
mark x= 0.5 y= 0.0 line=solid
mark y= 1000 line=short
.GE -10
.dh Defaults
If the line type is not given then a solid line
is used.
.hd
.ds HS Errors
.sh ERRORS
.np
The main causes of errors are
incorrect plot specifications or garbage
intermingled with the data.
.np
If a construction is not recognised in the plot
specifications (such as misspelt words) then the program
will terminate, giving the line number and probable cause
of the error.
For example:
.EG +10 1
Error in file EX5 at line 7 - legend occurs twice
.GE -10
states that there was a second occurance of legend
on line 7. ("Legend" can only occur once).
.np
If the data has garbage or unrecognisable information
imbedded in it then plot skips over the garbage,
and gives a warning message at the conclusion
of the plotting of the graph.
The output might be:
.EG +10 2
warning in file data1 at line 200 - garbage data
warning in file test at line 101 - missing column
.GE -10
.ds HS Sample Plots
.bp
.sh "EXAMPLE ONE"
.np
It is now possible to completely specify the
format of the graph, and examples of complete
plot specifications appear below:
.EG +10 11
legend "EXAMPLE GRAPH"
xaxis "INCOME"
yaxis "RATE OF TAX EVASION"
comment we plot col 1 versus col 2
plot x= 1 y= 2
data
0 0
100 1
150 2
200 5
250 13.5
300 19.9
350 16.5
400 17.8
450 22.1
500 25
800 30
1000 33.3
.GE -10
and this would produce the graph shown below:
.bp
.sh "EXAMPLE TWO"
A further example is given below to ensure the operation
of plot is clear:
.EG +10 10
legend "example two" key at end
xaxis from 0 to 20 by 2
yaxis from -10 to 10
plot "DATA SET 1" x= 1 y= 2
data fileone
plot "DATA SET 2" x= 1 y= 3
data filetwo
.GE -10
Note that "fileone" and "filetwo" are
just files that contain columns af data.
.rm x1
.bp
.rm fo
.rs
.sp 3i
.cu 2
.ce 2
PLOT
.sp
A USER'S GUIDE
.sp 6
.ti +5
.fi
.ad
.ll -10
.in +10
This document introduces and describes an automated
plotting program available under UNIX
for producing high quality graphs on
Tektronix terminals and plotters.
.br
.ll +10
.in -10
.sp 8
.tl '''Richard Grevis'
.tl '''January 1979'