Prefabs


Welcome     Gallery     Handbook


Manual page for Prefabs(PL)

AVAILABLE PREFABS


chron - chronological data (dates, times, etc); tabulate by week, month, etc.

dist - frequency distribution histogram on a data field

lines - line plots with optional data points and error bars, up to 4 groups

pie - pie graphs

stack - stacked bar graphs, up to 4 levels

scat - scatterplots

vbars - bar graph of 1 or 2 groups with error bars

vbars - with error bars only

WHAT ARE PREFABS?

Prefabs are the easiest way to get started with ploticus. You can quickly generate common types of plots without coding any ploticus scripts. Just supply several key parameters on the command line or in the data file. Everything else uses defaults.

The -prefab command line option tells pl to use a prefab. Any of the other command options may also be used along with -prefab. For example, to use the scat scatterplot prefab you might use a command such as this:

pl -prefab scat -png data=results.dat x=2 y=4 -scale 0.7

Prefab scripts are ordinary ploticus scripts. A collection of prefab scripts are included with ploticus in the ./prefabs directory. You can use this directory or set up one of your own. An environment variable called PLOTICUS_PREFABS must exist and contain the full path name of the directory where prefab scripts reside.


PARAMETERS

Some parameters are standard (recognized by most of the prefabs); others are specific to the individual prefabs.

Parameters may be supplied on the pl command line as var=value pairs as seen in the above example.

Most parameters may also be embedded in an input data file, using the #set construct:

 #set x = 2
 #set y = 3
 #set title = Correlation of WBC vs. T-Chol

Some parameters cannot be set from within the data file because they control data scanning. These are data, delim, header, and comment. There may be others as noted for individual prefabs.


OUTPUT FILE NAMES

The -o option may be used to specify output file name explicitly. If -o is not given, output file naming is similar to that of pl in other contexts. For the above example the output file would be named scat.png .


CUSTOMIZATION

Prefabs allow quick looks at data, but there are often details that would be nice to control but can't be adjusted because there is no command line parameter to do so. One way to proceed is to copy a prefab script to your own directory and then modify your copy as needed. Another option is to make a new prefab variant in the prefabs directory.




EXAMPLES

A number of examples are included for each prefab. The command that was used to produce each one is shown (the command line options -gif -scale 0.7 -tightcrop were also used but are omitted for brevity). All of the examples may be demonstrated by going to the prefabs directory (the command echo $PLOTICUS_PREFABS will show the name of that directory), and entering the given command.


HINTS

The following pl command line options may be very useful with prefabs: -scale, -color, -backcolor, -tightcrop, and perhaps -font.

Be careful not to confuse prefab parameters with pl command line options . Prefab parameters are given this way: paramname=value. Command line options are given this way: -option or -option value.

Most shells allow a backslash (\) for breaking up long commands into two or more lines.

You can get a multi line title by splitting it over two lines, eg:

    pl -prefab pie1 data=data1 fld=3 label=1 title="Travel expenditures
    By department
    Fiscal year 2000"






STANDARD PARAMETERS FOR PREFABS

The following parameters are accepted by all prefabs unless otherwise stated. The data parameter is always required.

data

Name of data file. Always required. May be given as - if data are to be read from standard input.

x

Data field to plot in X. Either a number (eg 2 for the 2nd field) or a name if a data file contains a header.

y

Data field to plot in Y. Either a number (eg 2 for the 2nd field) or a name if a data file contains a header.

err

Data field for plotting vertical error bar around ( x, y ). If not specified no error bars will be drawn. Either a number (eg 2 for the 2nd field) or a name if a data file contains a header.

title

A plot title to be centered at the top. The parameter titledet is also available for controlling details of title placement and appearance.

xlbl

Label for X axis. The parameter xlbldet is also available for controlling details of X label placement and appearance. For example, to adjust the label downward 8/10 inch: -xlbldet=adjust=0,-0.8.

xrange

Range for numeric X axis. This is two values, a min and a max. Example: "xrange=0 100" . xrange causes automatic scaling in X to be disabled.

xinc

Increment amount for numeric X axis.

xlog

Logarithmic X axis. Allowable values are log and log+1.

xgrid

If yes, vertical grid lines will be drawn at each X stub. May also be specified as a linedetails attribute.

ylbl

Label for Y axis. The parameter ylbldet is also available for controlling details of Y label placement and appearance. For example, to adjust the label leftward 8/10 inch: -ylbldet=adjust=0,-0.8.

yrange

Range for numeric Y axis. This is two values, a min and a max. Example: "yrange=0 100" For prefabs where it is appropriate, yrange may also be given as yrange=0 which fixes the min at 0 but allows the max to be automatically determined from the data. When two values are given, yrange causes all automatic scaling in Y to be disabled.

yinc

Increment amount for numeric Y axis.

ylog

Logarithmic Y axis. Allowable values are log and log+1.

ygrid

If yes, horizontal grid lines will be drawn at each Y stub. May also be specified as a linedetails attribute.

autow

If yes, width of plotting area will be automatically determined by the data.

stubvert

If yes, X axis stubs will be rendered vertically.

delim

Data file field delimitation method, either space, comma, or tab. space is the default, and indicates that fields will be delimited on "white space". See data formats for more information.

header

yes if first non-comment line of data file contains field names. These names may be used to reference the data fields. Default is no.

comment

Indicates data file comment character or symbol. Default is //.

select

A conditional expression for selecting data records to include. One at-sign should be used, not two. Example: select="@1 = A"

include1

Specifies a file containing ploticus script code. The code is included after the plotting area has been set up but before the data display is drawn. May be useful in adding baselines, etc.

include2

Specifies a file containing ploticus script code. The code is included after the data display is drawn. May be useful for adding annotation.


USER-CONTRIBUTED PREFABS

User-contributed prefabs are welcome and may be sent to steve@sgpr.net; please include the prefab script file and a man page giving at least one working example.


data display engine  
Copyright Steve Grubb


Markup created by unroff 1.0,    September 14, 2001.