proc getdata


Welcome     Gallery     Handbook


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

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 standardinput attribute may be used). Example: filename: myfile.dat

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.

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

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 works for data having 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.
Note: Conditional expressions are interpreted once per data record thus performance is not stellar epecially for larger data sets.
Example: select: @@3 = g
This would select all data records having 3rd field equal to g.

filter multiline-text

This is a "script within a script", for the purpose of processing incoming data records as they are read. The filter script executes once for every data record read and is typically used for doing computations involving several fields within each record, or adding or deleting fields. It can not do operations across multiple data records, such as summations.

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 (##). Variables that are local only to the filter script are allowed but they must be declared using a ##declare statement. When a local variable is referenced two at-signs (@@) must be used. Incoming data fields may be referenced by number, e.g. use @@1 for the contents of the first field. Local variables and datafields are not available to the greater ploticus script. Variables from the greater ploticus script may be accessed within the filter script using one at-sign (@). They may not, however, be set.

The filter script is terminated using a blank line.

Note: if filter is used along with select, the select is applied first.

Note: results created by filter must use the same delimitation method as was used for the input. For example if you use delim: tab then you need to be sure that your filter produces tab-delimited fields.

Also note: Scripts are interpreted once per data record thus performance may be poor for larger data sets.

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.

 filter:
      ##declare DIFF
      ##if @@2 = M || @@3 = M
        ##exit
      ##endif
      ##set DIFF = $daysdiff(@@3,@@2)
      @@1 @@DIFF

There are several more filter examples in the FAQ

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.

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


Markup created by unroff 1.0,    June 26, 2001.