|
Manual page for proc_getdata(PL)
DESCRIPTION
proc getdata is used to access or define data for plotting.
proc getdata must be executed before any
data-based plotting can be done.
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.
Data may be specified at the end of the script file using
#intrailer/ #proc trailer (see EXAMPLES, below).
Conditional selection of data records.
Data filtering for purposes such as combining or rearranging fields,
performing calculations, truncating outliers, etc.
EXAMPLES
Virtually all of the Gallery examples use #proc getdata.
ACCEPTABLE DATA FORMATS
See
dataformats
PREREQUISITES
None.
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.
ERROR CONDITIONS
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" :
#proc getdata
...
#proc endproc
#if @NRECORDS = 0
#proc annotate
location: 3 3
text: No data found.
#exit
#endif
SETTING VARIABLES FROM A DATA FILE
Data files may contain embedded #set 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:
#set varname = value
varname will be declared and set to value. value may
contain embedded spaces or any other character. value may not
be a $function(), nor may it contain any other @variables.
None of the other script operators, such as #if, are supported in this context.
SETTING DATA FIELD NAMES
If you wish, you may assign names to data fields, and then be able to reference
data fields by name. If names are not assigned,
fields must be referenced by field number, where the first field is 1.
Use of field names may allow more readable code.
Field names may be assigned in the ploticus script file using the fieldnames
attribute. Field names may also be embedded in the data file (see the fieldnameheader
attribute).
MANDATORY ATTRIBUTES
Either data, file, or command must be specified
(see below).
ATTRIBUTES
data
multiline-text
Literal specification of plotting data. Terminates at
first blank (empty) line. Example:
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
file filename
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 standardinput attribute may be used).
Example: filename: myfile.dat
pathname filename
Name of a file containing plotting data.
The file will be opened directly.
This may be preferable for emulation environments where basic
unix commands such as cat(1) are not available.
Shell variables and metacharacters may not be used.
command shell command line
A shell command that will produce plot data on its standard output.
Example: command: cat mydat | uniq -c
fieldnames namelist
If specified, the names given in namelist may be
used in any plotting proc to identify data fields. namelist is a
space- or comma- delimited list of names. Very lengthy lists
(> 200 characters long) should be space-delimited. Names may include
any alphanumeric characters with a maximum length of 38, and are case-insensitive.
Embedded spaces are not allowed.
Example: fieldnames: date group n
fieldnameheader yes | no
If yes, the first non-comment line in the data is expected to
hold a list of field names. See the fieldnames attribute for more information
about field names.
If the data attribute is used, use of fieldnames
is preferred over fieldnameheader.
standardinput yes | no
If yes, data is read from the standard input.
#intrailer
Indicates that a data attribute
will be given in a #proc trailer, at the end of the script file.
See EXAMPLES, below.
commentchar
string
A character or group of characters that is
used to signify a comment in the data file.
Commented lines will be skipped.
Default is //.
Example: commentchar: #
delim space | comma | tab
The type of delimiting method to be used when
parsing the data. See
dataformat
for details.
Example: delim: comma
showresults yes | no
If yes, the results, after selecting and/or filtering, are
written to the diagnostic file,
which may be useful in debugging, etc.
rotate yes | no
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 proc processdata.
Example: see
bars1
select
conditional-expression
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 (@@) prefix.
select cannot be used along with the data attribute.
Hint: use the showresults attribute when debugging.
Example: select: @@3 = g
This would select all data records having 3rd field equal to g.
filter
multiline-text
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.
The embedded script will be applied once to every incoming data record.
The script should produce some "output"; generally the last statement is a
##print.
The output must use the same delimitation method as the input.
The script uses the same syntax
as the greater ploticus script, except that:
-
-
directives must begin with two pound signs (##) instead of one
-
local variables begin with two at signs (@@) instead of one
-
fields on the incoming data record are accessed like this: @@1 for
the first field, @@2 for the second, etc. If you are using field
names, these may be used as well, eg: @@score.
-
the only directives that may be used are
##set, ##if, ##elseif, ##else, ##print, ##call,
and ##exit
Other things worth noting:
-
MORE EXAMPLES
Data specification may be located at the end of the script file
by using #intrailer and #proc trailer. 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:
#proc getdata
#intrailer
other #procs, etc.
#proc trailer
Data: 0.3 0.5 2.3
3.5 9.4 1.4
..etc..
end of file
|
 data display engine
Copyright Steve Grubb
|