scatplot.1

speech signal process tools

.\" @(#)scatplot.1	1.1 1/6/87 EPI
.TH SCATPLOT 1-SPS 1/6/87
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Processing, Inc.
.SH NAME
scatplot - make a scatter plot
.SH SYNOPSIS
.B scatplot
[
.BI \-p " range"
] [
.BI \-e " range"
] [
.BI \-s " symbols"
] [
.BI \-x " range"
]
.br
[
.BI \-y " range"
] [
.BI \-t " text"
] [
.BI \-X " text"
] [
.BI \-Y " text"
]
.I file1 file2 ...
.SH DESCRIPTION
.PP
.I Scatplot
makes a scatter plot of a pair of elements from multiple SPS files
.I file1, file2, ....
Actually, it generates
commands that are suitable for 
.IR plotas "(1) or"
.IR stou "(1)."
If "-" is supplied in place of
.I file1,
then standard input is used.
.PP
If the \fB\-p\fP option is omitted, then the entire contents
of
.I file1
is used as the default range.  If more than  one file  is given, then
the  range  must  exist  in  these other  files as  well, otherwise a
message is  printed on  stderr and  the program  terminates with exit
(1).  
.PP
The  \fB\-e\fP  option  specifies  which elements  to plot.   An even
number of elements must always  be given  since there  are no default
elements to plot.  The first pair of elements is mapped  to the first
file, the second pair of elements is mapped to the second file and so
on upto the last file or until no other pair of  elements remains, in
which  case  the  last pair  of elements  is mapped  to the remaining
files.  The first element in the pair  is plotted  along the abscissa
and the second element along the ordinate.  Default  symbols are used
to distinguish between multiple files, but  they can  be overriden by
the \fB\-s\fP option.  
.PP
For
.I file1, scatplot
finds the maximum and  minimum values in the specified range
and computes appropriate scales for the 
.I x
and 
.IR y\- axes.
This automatic scaling can be overriden by the
.B \-x
and
.B \-y
options.
Care should be taken when making a scatter plot of multiple files
with varying ranges.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-p " first:last"
.TP
.BI \-p " first:+incr
Determines the range of points to be plotted.  In the first form, a
pair of unsigned integers gives the first and last points of the range.  
If 
.I first
is omitted, 1 is used.  If 
.I last 
is omitted, the last point in the file is used.  The second form is
equivalent to the first with 
.I "last = first + incr".
.TP
.BI \-s " symbols [xo*abcdefghijkl]"
Plot the scatter plot using the symbols specified.   The first symbol
is mapped to the first file, the second symbol to the second file and
so on upto the last file.   However, there  must be  exactly the same
number of symbols as there are input files.  The  default symbols are
given in brackets.  
.PP
The position of the symbols
.I 'x'
and
.I 'o'
have been modified so that the plotting point falls very close to
the "center" of the character.  Other characters will not have their
centers exactly at the plotting points.
.TP
.BI \-e " elements"
Determine which elements within a record to plot.   The elements must
be seperated by a comma.  The first pair of elements is mapped  to the
first
file, the second pair of elements is mapped to the second file and so
on upto the last file or until no other pair of  elements remains, in
which  case  the  last pair  of elements  is mapped  to the remaining
files.  The first element in the pair  is plotted  along the abscissa
and the second element along the ordinate.
.TP
.BI \-x " low:high"
Specifies lower and upper limits for the x-axis, disables
automatic computation of limits.
.TP
.BI \-y " low:high"
Specifies lower and upper limits for the y-axis, disables
automatic computation of limits.
.TP
.BI \-t " text"
Print a line of text above the graph.
.TP
.BI \-X " text"
Print a line of text below the graph.
.TP
.BI \-Y " text"
Print a line of text along the left side of the graph going upwards.
.SH EXAMPLES
.TP
\fBscatplot \-p\fI1:500\fP \-s\fIxo \fB\-e\fI5,6,15,19 file1 file2\fB | stou | mcd\fP
makes a scatter plot (using the letter \fIx\fP for file1 and the
letter \fIo\fP for file2) of element 5 versus element
6 in \fIfile1\fP and of element 15 versus element 19
in \fIfile2\fP across the record range 1 to 500. The plot is
displayed on a Masscomp Graphics Terminal.
.TP
.BI "scatplot " <options> " | plotas | tpen | ipr -Ltektronix"
plots on the Imagen
.TP
.BI "scatplot " <options> " | stou | tek | ipr -Ltektronix"
also plots on the Imagen, but a scaling factor may need to be 
specified for tek. 
.TP
.BI "scatplot " <options> " | plotas | tpen"
plots on a Tektronix terminal
.TP
.BI "scatplot " <options> " | stou | tek"
also plots on a Tektronix terminal. 	
.SH "SPS HEADERS"
.PP
.I Scatplot
reads the following fields from the SD file header:
.I common.ndrec,
.I common.tag.
.SH DIAGNOSTICS
.PP
.nf
scatplot: please give only one -e option.
scatplot: -e option: even number of elements required.
scatplot: please specify an element range with the -e option.
scatplot: data is not tagged in \fIfile\fP, cannot plot element 0.
scatplot: -s option: please specify exactly \fIn_symbols\fP symbols.
scatplot: start point after end point.
scatplot: only \fIn_points\fP in \fIfile\fP.
scatplot: only \fIn_records\fP records read in \fIfile\fP.
scatplot: calloc: could not allocate memory for \fIarray\fP.
scatplot: d_mat_alloc: could not allocat memory \fImatrix\fP.
scatplot: fatal error: constant element in \fIfile\fP at element \fIn_ele\fP.
scatplot: please use the -x option.
scatplot: please use the -x option and the -y option.
scatplot: please use the -y option.
scatplot: command line too long: truncating string.
.fi
.SH EXPECTED CHANGES
.PP
Input x,y scales from all files.
.SH SEE ALSO
.IR plotpit (1\-SPS),
.IR plotsdm (1\-SPS),
.IR plotsdi (1\-SPS),
.IR mlplot (1\-SPS),
.IR genplot (1\-SPS),
.IR fea_element "(1\-SPS).\ "
.IR stou "(1),\ "
.IR plotas "(1),\ "
.IR mcd "(1),\ "
.IR tek "(1).\ "
.SH AUTHOR
.PP
.nf
Ajaipal S. Virdy, Entropic Processing, Inc.
.fi