.TH PLT 1 "19 December 2002" "plt 2.3" "WFDB Applications Guide"
.SH NAME
plt \- make 2-D plots
.SH SYNOPSIS
\fBplt\fR [ \fIdata-spec\fR ] [ \fIdata-file\fR ] [ [ \fIxcol\fR ] \fIycol\fR ] [ \fIoptions ...\fR ] [ \fB-T lw | lwcat\fR [ \fIlwcat-options\fR ] ]
.SH DESCRIPTION
.PP
This man page is intended as a supplement to the command-line help provided
by \fBplt\fR itself (using the \fB-h\fR option, see below).  If you have not
previously used \fBplt\fR, please look at the \fIplt Tutorial and Cookbook\fR,
which is included in the \fBplt\fR package (see \fBSOURCES\fR below).
.PP
\fBplt\fR is a non-interactive (command line-driven) plotting utility.
\fBplt\fR can produce publication-quality 2D plots in PostScript from
easily-produced text or binary data files, and can also create screen
plots under the X Window System.
.PP
All data presented to \fBplt\fR must be organized in rows and columns.
Columns are numbered beginning with zero, and each column contains
values for a variable that can be used as an abscissa (x coordinate),
ordinate (y coordinate), or (with appropriate options described below)
a grey level, color, or other plot attributes.  Rows are numbered
beginning with one, and each row contains a value for each column.
Within a \fIdata-file\fR, values are always arranged in row-major
order (all elements of row 1, followed by all elements of row 2,
etc.).
.PP
Usually, data must be in text form in order for \fBplt\fR to read them.
Each non-empty, non-comment line (row) in the input should contain a
value for each column that will be plotted; any additional
values or other extra text at the end of a row will be ignored.
Columns can be separated by any number of spaces or tabs.  Commas and
single or double quotation marks can also be used as column separators
with current versions of \fBplt\fR, though not with older versions.
It is not necessary to line up the values in each row.  There may also
be spaces or tabs at the beginning of a line, and these will also be
ignored.
.PP
If no \fIdata-file\fR is specified, \fBplt\fR reads data from its
standard input.  The command-line arguments \fIxcol\fR and \fIycol\fR
specify the column numbers for the abscissas and ordinates
respectively.  If only one column number is specified, it is taken as
\fIycol\fR, and \fBplt\fR generates a series of abscissas
automatically.  If the \fIdata-file\fR contains no more than two
columns, both \fIxcol\fR and \fIycol\fR may be omitted.
.PP
By default, \fBplt\fR reads all rows of the \fIdata-file\fR and scales
the x and y axes so that all data can be plotted.  An optional
\fIdata-spec\fR, a string beginning with a colon (:), can be used to
select a subset of the rows in the \fIdata-file\fR.  For details on
using a \fIdata-spec\fR, and for information about reading binary data
files using \fBplt\fR, see the \fIplt Tutorial and Cookbook\fR.
.PP
\fBplt\fR recognizes a large number of \fIoptions\fR for controlling
and customizing plots.  To see a summary of all options, run ``\fBplt -h\fR'';
if this command is followed by one or more strings (which should not
begin with hyphens), \fBplt\fR prints one-line summaries of all
options beginning with those strings only.
.PP
\fBplt\fR can read its options from command-line arguments, from a
\fIformat file\fR (specified using the \fB-f\fR option), or from a
\fIformat string\fR (supplied on the command line, following the
\fB-F\fR option).   When using format files or format strings, omit
the hyphen (-) before each option.
.SS Options
Following is a brief summary of \fBplt\fR's options.  Note that many
options require arguments.  \fBplt\fR chooses a suitable default for most
such arguments if the argument is supplied as `\fB-\fR'.  See the
\fIplt Tutorial and Cookbook\fR for further details.
.TP
\fB-p\fR\fI plot-styles\fR
Specify style(s) for data plots.  Available \fIplot-styles\fR include
`\fBc\fR', `\fBC\fR', `\fBe+\fR\fIc\fR', `\fBe-\fR\fIc\fR', `\fBe:\fR\fIc\fR',
`\fBE+\fR\fIn\fR', `\fBE-\fR\fIn\fR', `\fBE:\fR\fIn\fR', `\fBf\fR', `\fBi\fR',
`\fBl\fR', `\fBm\fR', `\fBn\fR', `\fBN\fR', `\fBo\fR', `\fBO\fR',
`\fBs\fR\fIc\fR', `\fBS\fR\fIn\fR', and `\fBt\fR'.
.TP
\fB-s\fR\fI elements\fR
Suppress \fIelements\fR of output.  Elements that can be suppressed
include `\fBe\fR' (erasing the screen or beginning a new page before
plotting), `\fBa\fR' (anything associated with axes), `\fBx\fR' (anything
associated with the x axis), `\fBy\fR' (anything associated with the y
axis), `\fBg\fR' (the grid), `\fBm\fR' (x and y axis tick marks),
`\fBn\fR' (x and y tick mark numbers), `\fBt\fR' (x and y axis labels and
plot title), `\fBl\fR' (user-supplied labels), `\fBp\fR' (data plots),
and `\fBf\fR' (``figures'' -- boxes, line segments, arrows, and legends).
In addition, these \fIelements\fR modify the effects of any other elements
that follow:  `\fBX\fR' (restrict effects to x axis), `\fBY\fR' (restrict
effects to y axis), and `\fBA\fR' (apply effects to both axes);  and the
element `\fBC\fR' reenables all elements.
.TP
\fB-X\fR\fI xmin xmax\fR
Set the x-axis range (see also \fB-xa\fR).
.TP
\fB-Y\fR\fI ymin ymax\fR
Set the y-axis range (see also \fB-ya\fR).
.TP
\fB-t\fR\fI title\fR
Set the title for the plot (enclose \fItitle\fR in quotes if it contains
whitespace or begins with `\fB(\fR' or `\fB[\fR').
.TP
\fB-T\fR\fI type\fR
Specify the output \fItype\fR, which may be \fBxw\fR (X11 window, the default
under Unix or Linux and not available under MS-Windows), or \fBlw\fR
(PostScript, the default under MS-Windows).
.TP
\fB-g\fR\fI grid-mode\fR
Specify the grid style, which may be \fBin\fR, \fBout\fR (default), \fBboth\fR,
\fBnone\fR, \fBsym\fR (make symmetric axes at top and right), \fBgrid\fR
(extend major ticks across the entire plot), \fBxgrid\fR, \fBygrid\fR, or
\fBsub\fR (extend all ticks across the entire plot).
.TP
\fB-h\fR [ \fI option-prefix ... \fR ]
Show help on options beginning with \fIoption-prefix\fR (which should not
begin with `\fB-\fR').  If \fIoption-prefix\fR is omitted, show help on
all options.
.PP
Within the next group of options, those with upper-case names (`\fB-A\fR',
`\fB-B\fR', ...) use \fIwindow coordinates\fR between (0,0) and (1,1);
those with lower-case names (`\fB-a\fR', `\fB-b\fR', ...) use \fIdata
coordinates\fR.
.TP
\fB-a\fR\fI x0 y0 x1 y1\fR
Draw an arrow to \fI(x0,y0)\fR from \fI(x1,y1)\fR.
.TP
\fB-A\fR\fI xw0 yw0 xw1 yw1\fR
Draw an arrow to \fI(xw0,yw0)\fR from \fI(xw1,yw1)\fR.
.TP
\fB-b\fR\fI x0 y0 x1 y1\fR
Draw a box with opposite corners at \fI(x0,y0) and \fI(x1,y1)\fR.
.TP
\fB-B\fR\fI xw0 yw0 xw1 yw1\fR
Draw a box with opposite corners at \fI(xw0,yw0) and \fI(xw1,yw1)\fR.
.TP
\fB-c\fR\fI x0 y0 x1 y1\fR
Connect points \fI(x0,y0)\fR and \fI(x1,y1)\fR.
.TP
\fB-C\fR\fI xw0 yw0 xw1 yw1\fR
Connect points \fI(xw0,yw0)\fR and \fI(xw1,yw1)\fR.
.TP
\fB-d\fR\fI x0 y0 x1 y1\fR
Draw a dark (filled) box with opposite corners at \fI(x0,y0) and \fI(x1,y1)\fR.
.TP
\fB-D\fR\fI xw0 yw0 xw1 yw1\fR
Draw a dark (filled) box with opposite corners at \fI(xw0,yw0) and
\fI(xw1,yw1)\fR.
.TP
\fB-l\fR\fI x y tbc label-string\fR
Print \fIlabel-string\fR at \fI(x,y)\fR.  The \fItbc\fR argument is a
two-character text box coordinate that specifies how the label is to be
positioned relative to \fI(x,y)\fR;  the default (\fBCC\fR) centers the
string at \fI(x,y)\fR.
.TP
\fB-L\fR\fI xw yw tbc label-string\fR
As for \fB-l\fR, but using window coordinates \fI(xw,yw)\fR.
.TP
\fB-w\fR\fI configuration subwindow\fR
Confine the plot to a predefined window, specified by the arguments.
\fIconfiguration\fR specifies the number of subwindows (panels), using
one of `\fBm\fR' (1), `\fBb\fR' (2), or `\fBq\fR' (4), and \fIsubwindow\fR'
specifies which panel is to be plotted (0 or 1 for `\fBm\fR'; 0, 1, or 2
for `\fBb\fR'; or 0, 1, 2, 3, or 4 for `\fBq\fR').  In each case, subwindow
0 creates the frame of the entire plot, and the other subwindows refer to
regions where data can be plotted.  Use this option with `\fB-o\fR' or
`\fB-s e\fR' to create multi-panel plots in stages without starting a new page
or erasing the window before starting each new stage.
.TP
\fB-W\fR\fI xp0 yp0 xp1 yp1\fR
Define the region of the page in which to plot.  The arguments are
\fIpage coordinates\fR;  the page coordinates (0,0) and (1,1) correspond to
the lower left and upper right corners of the page.
.TP
\fB-f\fR\fI format-file\fR
Read options from the specified \fIformat-file\fR.
.TP
\fB-fa\fR\fI format-file\fR
Record the current axis parameters as options in the specified
\fIformat-file\fR (for use with a later \fBplt\fR command).  The
previous contents of \fIformat-file\fR, if any, will be overwritten.
.TP
\fB-F\fR\fI format-string\fR
Read options from the specified \fIformat-string\fR.
.TP
\fB-o\fR
Suppress all output except data plots.
.TP
\fB-cz\fR\fI xfrom xincr\fR
Generate abscissas, beginning with \fIxfrom\fR (default: 0) and
incrementing by \fIxincr\fR (default: 1) at each step.
.TP
\fB-ex\fR
Don't exclude points outside axis limits.
.TP
\fB-hl\fR\fI x y tbc n file\fR
Print the next \fIn\fR (default: 1000) lines of the specified \fIfile\fR as a
label, placing the reference point for the first line of the label at data
coordinates \fI(x,y)\fR.  The \fItbc\fR argument is defined as for \fB-l\fR and
is applied to each line of the label.  The \fIfile\fR is opened when first used
by \fB-hl\fR or \fB-vl\fR, and remains open, so that successive \fB-hl\fR or
\fB-vl\fR options referring to the same \fIfile\fR read and print successive
lines.  At most \fBMAXLABELFILES\fR (defined in \fBplt.h\fR, currently 6)
\fIfile\fRs of label strings can be open at once.
.TP
\fB-vl\fR\fI x y tbc n file\fR
As for \fB-hl\fR, but print the label in a vertical orientation (rotated
90 degrees counterclockwise).
.TP
\fB-le\fR\fI linenumber plotnumber\fR [ \fItext\fR ]
Define the specified \fIlinenumber\fR in the legend (see also \fB-lp\fR).
Line numbers in the legend begin with 0 (the top line);  plot numbers also
begin with 0 (these refer to the data plots, and are used here to determine
the line style for the entry's sample plot segment).  The \fItext\fR is
printed to the right of the sample plot segment.  To create an entry with
more than one line of text, use additional \fB-le\fR options with different
\fIlinenumber\fRs as necessary, omitting the \fIplotnumber\fR (use `\fB-\fR')
for all but the first.  If the same data are plotted more than once in a
single figure to create an overlay (for example, using symbols over line
segments), an overlaid legend entry can be created using additional \fB-le\fR
options with the same \fIlinenumber\fR and different \fIplotnumbers\fR,
omitting the \fItext\fR for all but the first.
.TP
\fB-lp\fR\fI xw0 yw0\fR [ \fIboxscale\fR [ \fIseglength\fR [ \fIopaque\fR ] ] ]
Define the window coordinates \fI(xw0, yw0)\fR of the upper left corner of
the plot legend text, and other attributes for the plot legend (key).
\fBplt\fR determines the size of the box it draws around the legend, but
the calculated width of the box is multiplied by \fIboxscale\fR.  The
\fIseglength\fR option specifies the length of the sample plot segments,
as a fraction of the x-axis length (default: 0.05).  If \fIopaque\fR is
`\fByes\fR' (default), the background of the legend is opaque white;
otherwise, the background is transparent (any previously drawn material
remains visible through the legend box).  Unless a \fB-lp\fR option is
provided, no legend is printed.
.TP
\fB-lx \fR [ \fIbase\fR [ \fIsubticks\fR ] ]
Draw a logarithmic x-axis;  \fIbase\fR is the base of the logarithms (default:
10), and \fIsubticks\fR is either `\fByes\fR' or `\fBno\fR'.  If the axis
has a small number of major ticks, \fBplt\fR draws subticks by default;
use the \fIsubticks\fR argument to change \fBplt\fR's default behavior.
.TP
\fB-ly \fR [ \fIbase\fR [ \fIsubticks\fR ] ]
Draw a logarithmic y-axis.
.TP
\fB-tf\fR\fI file\fR [ \fItbc\fR ]
Load the text string array from the specified \fIfile\fR.  Each line of the
\fIfile\fR defines an element of the string array;  using plot styles
\fBc\fR or \fBt\fR, these strings can be plotted in the same manner as
data points.  The optional \fItbc\fR specifies how the positions of the
strings are to be modified when they are printed, in the same way as for
\fB-l\fR;  by default, the strings are centered on the coordinates specified
for them.
.TP
\fB-ts "\fR\fIstring0 string1 ...\fB"\fR [ \fItbc\fR ]
Load the text string array from the quoted argument (whitespace separates
strings in the array) rather than from a file;  otherwise, this option is
the same as \fB-tf\fR.
.TP
\fB-fs "\fR\fIstring0 string1 ...\fB"\fR
Load the font string array from the quoted argument.  Using appropriate
plot style (\fB-p\fR) options, the strings can be used to change the font,
line style (solid, dotted, dashed, etc.), or drawing color.
.TP
\fB-x\fR\fI string\fR
Set the x-axis title to \fIstring\fR (which must be quoted if this option
is used on the command line or if \fIstring\fR begins with `(' or `[').
.TP
\fB-xa\fR\fI xmin xmax tick fmt tskip ycross\fR
Specify the x-axis range (as \fIxmin\fR to \fIxmax\fR); the interval between
x-axis tick marks; the format, \fIfmt\fR, in which to print the numbers (e.g.,
``\fB%.3f\fR'', ``\fB%.2e\fR'';  any format that \fBprintf(3)\fR can use for
printing floating-point numbers is acceptable); the number of ticks per
labelled tick, \fItskip\fR; and \fIycross\fR, the point on the y-axis that the
x-axis should cross, in y-units.  Any of these parameters may be supplied as
``-'', which causes \fBplt\fR to choose a reasonable value based on the input
data.
.TP
\fB-xe\fR\fI xmin-error xmax-error\fR
Use this option to specify the amount by which the x-axis range is allowed
to exceed the range of x-values in the input data, when \fBplt\fR determines
the x-axis range automatically.
.TP
\fB-xm\fR\fI tick-base\fR
Make x-axis ticks be multiples of the specified \fItick-base\fR.
.TP
\fB-xo\fR\fI x-axis-offset\fR
Move the x-axis down by \fIx-axis-offset\fR (expressed as a fraction of the
y-axis length).
.TP
\fB-xr\fR
Draw the x-axis at the top of the plot
.TP
\fB-xt\fR\fI x label\fR [ \fItick-size\fR ]
Add an extra labelled tick at the specified \fIx\fR position, and label it
with the specified \fIlabel\fR (which may be any string).  The optional
\fItick-size\fR argument specifies the length of the added tick, as a fraction
of the default length for labelled ticks (e.g., a value of 1.5 makes the
added tick 50\% longer than the standard size).
.TP
\fB-xts\fR\fI x\fR [ \fItick-size\fR ]
Force a labelled tick to appear on the x-axis at the specified \fIx\fR
(the positions of the other labelled x-ticks are adjusted accordingly).
\fItick-size\fR is defined as for \fB-xt\fR.
.TP
\fB-y\fR\fI string\fR
Set the y-axis title to \fIstring\fR (see \fB-x\fR).
.TP
\fB-ya\fR\fI ymin ymax tick fmt tskip xcross\fR
Set up the y-axis (see \fB-xa\fR).
.TP
\fB-ye\fR\fI ymin-error ymax-error\fR
Set the allowable error in the y-axis range (see \fB-xe\fR).
.TP
\fB-ym\fR\fI tick-base\fR
Make y-axis ticks be multiples of the specified \fItick-base\fR.
.TP
\fB-yo\fR\fI y-axis-offset\fR
Move the y-axis to the left by \fIy-axis-offset\fR (expressed as a fraction of
the x-axis length).
.TP
\fB-yr\fR
Draw the y-axis at the right edge of the plot.
.TP
\fB-yt\fR\fI y label\fR [ \fItick-size\fR ]
Add an extra labelled tick at the specified \fIy\fR position (see \fB-xt\fR).
.TP
\fB-yts\fR\fI y\fR [ \fItick-size\fR ]
Force a labelled tick to appear on the y-axis at the specified \fIy\fR
(see \fB-xts\fR).
.TP
\fB-dev\fR\fI pterm option\fR
Process \fIoption\fR only if the value of \fBPTERM\fR is \fIpterm\fR.
The \fB-dev\fR option may be useful in scripts that produce screen or
printed plots in different formats.
.TP
\fB-sf\fR\fI name specification\fR
Create a new font group with the specified \fIname\fR and set its
specifications (font, point size, color/grey level, line width, and line
style).  See the chapter titled \fIColors, Line Styles, and Fonts\fR in
the \fIplt Tutorial and Cookbook\fR for details.
.TP
\fB-ch\fR\fI height-factor width-factor\fR
Modify the height and width of all characters printed in the plot by
the specified factors.
.TP
\fB-size\fR\fI fscl width height left-margin bottom-margin\fR
Specify the size and position of the plot on the page.  The \fIwidth\fR,
\fIheight\fR, \fIleft-margin\fR, and \fIbottom-margin\fR are specified
in \fIinches\fR (1 inch = 25.4 mm).  \fIfscl\fR is a factor applied to the
point size of all printed characters, \fIindependently\fR of the scaling
applied to the rest of the plot.  This option is effective for printed plots
only.
.SS Screen and printed plots
.PP
By default, \fBplt\fR makes an X11 screen plot.  To make a printed
plot, use the option \fB-T lw\fR, and pipe the output of \fBplt\fR to
\fBlwcat\fR(1).  Under Unix, GNU/Linux, or MacOS/X, \fBlwcat\fR uses
the standard \fBlpr\fR print spooler to send \fBplt\fR's output in
PostScript format to the default printer.  When running with a
Cygwin/bash window under MS-Windows, or when using \fBlwcat\fR's
\fB-gv\fR option under Unix or Linux, the PostScript output is
displayed on-screen using GhostScript (\fBGSView\fR under MS-Windows,
or \fBgv\fR otherwise; these programs can save the output in a file or
send it to a printer).
.SH EXAMPLES
.PP
Create a text file with the following contents:
.br
	0  0  0
.br
	1  1  1
.br
	2  4  8
.br
	3  9 27
.br
	4 16 64
.br
and call the file \fIpowers\fR.  Plot the first column vs. the second by:
.br
	\fBplt powers 0 1 -t "Squares of small integers" -x "Integer" -y "Square"\fR
.br
The same file can be used to generate a number of different plots, by
choosing different columns.  To plot the third column vs. the first, try:
.br
	\fBplt powers 2 0 -t "Marshmallows" -x "Mass (kg)" -y "Height (m)"\fR
.SH SEE ALSO
.PP
\fBimageplt\fR(1), \fBlwcat\fR(1), \fBpltf\fR(1)
.PP
The \fIplt Tutorial and Cookbook\fR (a book-length introduction to \fBplt\fR,
included in the \fBplt\fR source package, and also available at
\fBhttp://www.physionet.org/physiotools/plt/plt/doc/book.pdf\fR) contains many
more examples.
.SH AVAILABILITY
\fBplt\fR is available as part of PhysioToolkit (see \fBSOURCES\fR below) under
the GPL.
.SH AUTHORS
\fBplt\fR was originally written by Paul Albrecht, and is currently maintained
by George B. Moody (\fBgeorge@mit.edu\fR).
.SH SOURCES
\fBhttp://www.physionet.org/physiotools/plt/\fR