#set TITLE = "proc getdata"
#include top
 
.LP
\fBproc getdata\fR accesses or defines data for plotting.
\fBproc getdata\fR must be executed before any
data-based plotting can be done.

#include space
.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
Conditional selection of data records (\fCselect\fR).
.LP
Data filtering (\fCfilter\fR) for purposes such as combining or rearranging fields,
performing calculations, truncating outliers, etc.
.LP
Field names may be assigned explicitly (\fCfieldnames\fR or \fCfieldnamerows\fR), or via a data file
header line (\fCfieldnameheader\fR).  These names can then be used anywhere a
data field reference is expected.
.LP
Data sets with variable number of fields per row can be accomodated by
setting a maximum \fCnfields\fR value.  
.LP
Data may be located at the end of the script file, to get it out of the way (\fC#intrailer\fR).


#include space
.SH Examples
Virtually all of the Gallery examples use #proc getdata.


#include space
.SH Acceptable data formats
See
#set FILE = "dataformat.html"
#set TAG = "dataformat"
#include link
\0.

#include space
.SH Prerequisites
None.

#include space
.SH Troubleshooting
Set \fCshowresults: yes\fR in order to see the data after it is read and parsed.
Especially useful when working with \fCfilter\fR.

#include space
.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.

#include space
.SH Handling error conditions gracefully
If no data records were read, NRECORDS will be set to zero.
This may be tested using script code such as this, which generates
an image containing the words "No data found" :
.IP
.nf
\0#proc getdata
\0   ...
\0
\0#proc endproc
\0#if @NRECORDS = 0
\0  #proc annotate
\0  location: 3 3
\0  text: No data found.
\0
\0  #exit
\0#endif
.fi

.SH Setting variables from within a data file
Data files may contain embedded \fB#set\fR commands to set ploticus variables.
This may be a convenient way for title, labels, etc. to be driven by the data file.
The syntax is the same as in ploticus scripts: 
.IP
\fC#set \fIvarname\fC = \fIvalue\fR
.LP
\fIvarname\fR will be set to \fIvalue\fR.  \fIvalue\fR may
contain embedded spaces or any other character.  \fIvalue\fR may not
be a $function(), nor may it contain any other @variables.
None of the other script operators, such as \fB#if\fR, are supported in this context.


#include space
.SH Mandatory attributes
A data source (either \fCfile\fR, \fCpathname\fR, \fCcommand\fR, or \fCdata\fR) must be specified.
Default field delimitation method is \fCspacequoted\fR; \fCdelim\fR must be set for other
types such as tab-delimited or comma-quote delimited.

#include space
.SH Attributes
.LP
\fBdata\fR 
#set FILE = "attributetypes.html#text"
#set TAG = "multiline-text"
#include link
.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
Shell-expandable name of a file containing plotting data.
This name will be used along with cat(1) in a shell command, thus
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
\fBpathname\fR \fIfilename\fR
.IP
Name of a file containing plotting data.
The file will be opened directly.
Shell variables and metacharacters may not be used.

.LP
\fBcommand\fR \fIshell command line\fR
.IP
An external shell command that will produce plot data on its standard output.
.br
Example: \fCcommand: cat mydat | uniq -c\fR

.LP
\fBdelim\fR \fCspacequoted\fR | \fCwhitespace\fR | \fCcomma\fR | \fCtab\fR
.IP
The type of delimiting method to be used when 
parsing the data.  \fCspacequoted\fR is the default (\fCspace\fR is
equivalent to \fCspacequoted\fR).  See
#set FILE = "dataformat.html"
#set TAG = dataformat
#include link
for details.
.br
Example: \fCdelim: comma\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 
list delimited by spaces and/or commas.
Names may include any alphanumeric characters with a maximum length of 38, and are 
case-insensitive.
Field names may not contain embedded spaces or commas.
.br
Example: \fCfieldnames: date group n\fR

.LP
\fBfieldnamerows\fR 
#set FILE = "attributetypes.html#text"
#set TAG = "multiline text"
#include link
.IP
Same as \fCfieldnames\fR (see above), except that field names are given one per line.
Must be terminated by a blank line.
Example: 
.br
.nf
fieldnamerows:
  id
  type
  age
  sex
  

.LP
\fBfieldnameheader\fR  \fCyes\fR | \fCno\fR
.IP
Allows field names to be embedded in the input data.
If \fCyes\fR, the first non-comment line in the data is expected to
hold a list of field names.  See the \fCfieldnames\fR attribute above for more information
about field names.
If the \fCdata\fR attribute is used, use of \fCfieldnames\fR
is more efficent than \fCfieldnameheader\fR.

.LP
\fBnfields\fR  \fIn\fR
.IP
If specified, this sets the expected number of fields per record.
If a data row has more than the expected number of fields, extra fields are silently ignored. 
If a data row has less than the expected number of fields, blank fields are silently added.

.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 
#set FILE = "attributetypes.html#string"
#set TAG = "string"
#include link
.IP
A character or group of characters that is used to signify a comment in the data file.
Commented lines will be skipped.  Default is \fC//\fR.
Example: \fCcommentchar: #\fR

 

.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.


.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 applicable if your data set has one row.
(There still must be a blank line following the data attribute.)
To rotate more than one row, use \fBproc processdata\fR.
.br
Example: see 
#set FILE = "../gallery/bars1.htm"
#set TAG = bars1 
#include link

.LP
\fBselect\fR 
#set FILE = "condex.html"
#set TAG = "conditional expression"
#include link
.IP
This allows data records to be selected for inclusion based
upon a selection expression.  
Incoming data fields are referenced by number,
using a double at-sign (\fC@@@@\fR) prefix.  
\fCselect\fR cannot be used along with the \fCdata\fR attribute.
Hint: use the \fCshowresults\fR attribute when debugging.
.br
Example: \fCselect: @@@@3 = g\fR
.br
This would select all data records having 3rd field equal to \fCg\fR.

.LP
\fBfilter\fR 
#set FILE = "attributetypes.html#text"
#set TAG = "multiline text"
#include link
.IP
An embedded script which processes incoming data records.  Typical uses are for:
concatenating or splitting fields, doing on-the-fly date conversions,
or generating derived fields such as the sum of several fields or the difference 
between two fields.
.br
.br
.IP
The embedded script will be applied once to every incoming data record.
The script should produce some "output"; generally the last statement is a
\fB##print\fR.  
The output must use the same delimitation method as the input.
The script uses the same syntax as the greater ploticus script, except that:
.RS
.IP \(bu
directives must begin with two pound signs (\fC##\fR) instead of one
.IP \(bu
local variables begin with two at signs (\fC@@@@\fR) instead of one
.IP \(bu
fields on the incoming data record are accessed like this: \fC@@@@1\fR for
the first field, \fC@@@@2\fR for the second, etc.  If you are using field
names, these may be used as well, eg: \fC@@@@score\fR.
.IP \(bu
the only directives that may be used are 
\fB##set\fR, \fB##if\fR, \fB##elseif\fR, \fB##else\fR, \fB##print\fR, \fB##call\fR,
and \fB##exit\fR
.RE
.IP
Other things worth noting:
.RS
.IP \(bu
the filter script is terminated using a blank line.
.IP \(bu
use the \fCshowresults\fR attribute when debugging.
.IP \(bu
if \fCfilter\fR is used along with \fBselect\fR, the \fCselect\fR is applied first.  
.IP \(bu 
\fCfilter\fR cannot be used along with the \fCdata\fR attribute.
.IP \(bu
\fCfilter\fR can only access fields from one data record at a time.
.IP \(bu
variables from the ploticus script may be referenced within
the \fCfilter\fR script (use one at-sign \fC@@\fR).
Evaluation occurs before the filter script executes.
.IP \(bu
ploticus script #if/#else statements (single pound sign)
may be used to selectively execute portions of the filter script.
Interpretation occurs before the filter script executes.
.IP
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
\0filter:
\0     ##if @@@@2 = M || @@@@3 = M
\0       ##exit
\0     ##endif
\0     ##set DIFF = $daysdiff(@@@@3,@@@@2)
\0     ##print @@@@1 @@@@DIFF
.fi
.ft R
.IP
There are several more \fCfilter\fR examples in the 
#set FILE = "Faq.html#filter"
#set TAG = "FAQ"
#include link

#include space
.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
\0#proc getdata
\0#intrailer

\fIother #procs, etc.\fR

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


#include bottom
