.TH GETDATA PL "Ploticus data display engine"

.ig >>
<center>
<b>Ploticus data display engine</b> <small><a href="Copyright.html">Copyright Steve Grubb</a><br></small><br>
<a href="../doc/Welcome.html"><img src="../gallery/btn/welcome.gif"></a>
<a href="../gallery/index.html"><img src="../gallery/btn/gallery.gif"></a>
<a href="../doc/Contents.html"><img src="../gallery/btn/handbook.gif"></a>
<br><h1>Proc Getdata</h1>
</center>
.>>
 
.SH NAME
proc getdata

.SH DESCRIPTION
\fBproc getdata\fR is used to access or define data for plotting.
\fBproc getdata\fR must be executed before any
data-based plotting can be done.

.SH FEATURES
Data may be specified literally within the script file, 
or it may be located in an external file or 
be the result of an externally executed
command.  
.LP
Data may be specified at the end of the script file using
#intrailer/ #proc trailer (see EXAMPLES, below).
.LP
Conditional selection of data records.
.LP
Data filtering for purposes such as combining or rearranging fields,
performing calculations, truncating outliers, etc.

.SH EXAMPLES
Virtually all of the Gallery examples use #proc getdata.

.SH ACCEPTABLE DATA FORMATS
See
.ig >>
<a href="dataformats.html">
.>>
dataformats
.ig >>
</a>
.>>

.SH PREREQUISITES
None.

.SH VARIABLES THAT ARE SET
The variable NRECORDS will be set to the number of records read,
and the variable NFIELDS will be set to the number of fields per record.


.SH MANDATORY ATTRIBUTES
Either \fCdata\fR, \fCfile\fR, or \fCcommand\fR must be specified
(see below).

.SH ATTRIBUTES
.LP
\fBdata\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI multiline-text \fR
.ig >>
</a>
.>>
.IP
Literal specification of plotting data.  Terminates at
first blank (empty) line.  Example:
.nf
.ft C
data:   "Case 1"   0   4   4.1   
        "Case 2"   1   5   4.4  
        "Case 3"   2   2   4.0 
        "Case 4"   3   9   4.8

.fi
.ft R
.LP
\fBfile\fR \fIfilename\fR
.IP
Name of a file containing plotting data.
This name will be expanded by the shell so
exported shell variables and metacharacters may be part of the name.
A dash (-) may be used if data is to be read from the standard input,
(or the \fCstandardinput\fR attribute may be used).
Example: \fCfilename: myfile.dat\fR

.LP
\fBcommand\fR \fIshell command line\fR
.IP
A shell command that will produce plot data on its standard output.
.br
Example: \fCcommand: cat mydat | uniq -c\fR
 
.LP
\fBfieldnames\fR \fInamelist\fR
.IP
If specified, the names given in \fInamelist\fR may be
used in any plotting proc to identify data fields.  \fInamelist\fR is a 
space- or comma- delimited list of names.  Names may include any alphanumeric
characters with a maximum length of 38, and are case-insensitive.
.br
Example: \fCfieldnames: date group n\fR

.LP
\fBfieldnameheader\fR  \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, the first non-comment line in the data is expected to
hold a list of field names.  See \fCfieldnames\fR above for more information
about field names.

.LP
\fBstandardinput\fR \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, data is read from the standard input.

.LP
\fB#intrailer\fR
.IP
Indicates that a \fCdata\fR attribute
will be given in a #proc trailer, at the end of the script file.
See EXAMPLES, below.

.LP
\fBcommentchar\fR 
.ig >>
<a href="attributetypes.html#string">
.>>
\fI string \fR
.ig >>
</a>
.>>
.IP
A character or group of characters that is
used to signify a comment in the data file.
Commented lines will be skipped.
Example: \fCcommentchar: #\fR
 
.LP
\fBdelim\fR \fCspace\fR | \fCcomma\fR | \fCtab\fR
.IP
The type of delimiting method to be used when 
parsing the data.  See
.ig >>
<a href="dataformat.html">
.>>
dataformat
.ig >>
</a>
.>>
for details.
.br
Example: \fCdelim: comma\fR

.LP
\fBrotate\fR  \fCyes\fR | \fCno\fR
.IP
Allows data to be given all in one row, even when plotting proc
expects one record per instance (which most do).
Only works for data having one row.
(There still must be a blank line following the data attribute.)
To rotate more than one row, use \fBproc transform\fR.
.br
Example: see 
.ig >>
<a href="../gallery/bars1.htm">
.>>
bars1 
.ig >>
</a>
.>>

.LP
\fBselect\fR 
.ig >>
<a href="condex.html">
.>>
\fI conditional-expression \fR
.ig >>
</a>
.>>
.IP
This allows data records to be selected for inclusion based
upon a selection expression.  
Incoming data fields are referenced by number,
using a \fC@@\fR prefix.  
.br
Note: Conditional expressions are interpreted once per data record 
thus performance is not stellar epecially for larger data sets.
.br
Example: \fCselect: @@3 = g\fR
.br
This would select all data records having 3rd field equal to \fCg\fR.

.LP
\fBfilter\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI multiline-text \fR
.ig >>
</a>
.>>
.IP
This is a "script within a script", for the purpose of
processing incoming data records as they are read.
The syntax is the same as for ploticus scripts, except that
since this is really an "embedded" script, all operators
must begin with double pound signs (\fB##\fR) and all
variable references must begin with double at-signs (\fB@@\fR).
Incoming data fields are referenced by number,
using a \fC@@\fR prefix, where the first field is \fC@@1\fR.
.br
Note: if \fBfilter\fR is used along with \fBselect\fR, 
the select is applied first.
.br
Also note: Scripts are interpreted once per data record 
thus performance may be poor for larger data sets.
.br
Example: This filters out data records
having field 2 or field 3 equal to M.  It then
calulates the difference in days between two dates
and puts this difference in the variable DIFF.
Finally it "prints" incoming field 1 along with DIFF.
Thus the result of this #proc getdata
will have be data records having two fields.
.nf
.ft C
filter:
     ##declare DIFF
     ##if @@2 = M || @@3 = M
       ##exit
     ##endif
     ##set DIFF = $daysdiff(@@3,@@2)
     @@1 @@DIFF
.fi
.ft R

.LP
\fBshowresults\fR \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, the results, after selecting and/or filtering, are
written to the diagnostic file,
which may be useful in debugging, etc.


.SH MORE EXAMPLES
.LP
Data specification may be located at the end of the script file
by using \fB#intrailer\fR and \fB#proc trailer\fR.  This may be
useful in "getting the data out of the way", or with automated building
of script files.
Here is how this is done:
.nf
.ft C
#proc getdata
#intrailer

\fIother #procs, etc.\fR

#proc trailer
Data:	0.3 0.5 2.3
	3.5 9.4 1.4
	\fI..etc..\fR
\fIend of file\fR
