.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
-->
</STYLE>
<title>ploticus: prefabs</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>Prefabs</h2></td>
  <td align=right>
  <small>
  <a href="../doc/Welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  <a href="../doc/Welcome.html">Welcome</a> &nbsp; &nbsp;
  <a href="../gallery/index.html">Gallery</a> &nbsp; &nbsp;
  <a href="../doc/Contents.html">Handbook</a> 
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH Prefabs PL "14-SEP-2001   PL www.sgpr.net"

.SH AVAILABLE PREFABS
.ig >>
<table cellpadding=2 border=1><tr>
<td><a href="prefab_chron.html"><img src="../prefabs/chron1thm.gif" border=0></a><br>
<a href="prefab_chron.html">chron</a> - chronological data (dates, times, etc); tabulate by week, month, etc.
</td>
<td><a href="prefab_dist.html"><img src="../prefabs/dist1thm.gif" border=0></a><br>
<a href="prefab_dist.html">dist</a> - frequency distribution histogram on a data field
</td>
<td><a href="prefab_lines.html"><img src="../prefabs/lines1thm.gif" border=0></a><br>
<a href="prefab_lines.html">lines</a> - line plots with optional data points and error bars, up to 4 groups
</td>
<td><a href="prefab_pie.html"> <img src="../prefabs/pie1thm.gif" border=0> </a><br>
<a href="prefab_pie.html">pie</a> - pie graphs
</td>
</tr>
<td><a href="prefab_stack.html"><img src="../prefabs/stack1thm.gif" border=0></a><br>
<a href="prefab_stack.html">stack</a> - stacked bar graphs, up to 4 levels</td>
</td>
<td><a href="prefab_scat.html"><img src="../prefabs/scat2thm.gif" border=0></a><br>
<a href="prefab_scat.html">scat</a> - scatterplots 
</td>
<td><a href="prefab_vbars.html"><img src="../prefabs/vbars2thm.gif" border=0></a><br>
<a href="prefab_vbars.html">vbars</a> - bar graph of 1 or 2 groups with error bars
</td>
<td><a href="prefab_vbars.html"><img src="../prefabs/vbars3thm.gif" border=0></a><br>
<a href="prefab_vbars.html">vbars</a> - with error bars only
</td>
</tr>
</table>
<br>
.>>


.SH 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.
.LP
The \fC-prefab\fR command line option tells pl to use a prefab.
Any of the other command options may also be used along with \fC-prefab\fR.
For example, to use the \fBscat\fR scatterplot prefab you might use
a command such as this:
.IP
\fCpl -prefab scat  -png  data=results.dat  x=2  y=4  -scale 0.7\fR
.LP
Prefab scripts are ordinary ploticus scripts.  A collection of prefab scripts
are included with ploticus in the \fC./prefabs\fR 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.

.ig >>
<br><br><br>
.>>

.LP
\fBPARAMETERS\fR
.LP
Some parameters are 
.ig >>
<a href="#std">
.>>
\0standard
.ig >>
</a>
.>>
(recognized by most of the prefabs);
others are specific to the individual prefabs. 
.LP
Parameters may be supplied on the \fBpl\fR command line as \fIvar=value\fR
pairs as seen in the above example. 
.LP
Most parameters may also be embedded in an input 
data file, using the #set construct:
.IP
.nf
.ft C
\0#set x = 2
\0#set y = 3
\0#set title = Correlation of WBC vs. T-Chol
.ft R
.fi
.LP
Some parameters cannot be set from within the data file because they control
data scanning.  These are \fBdata\fR, \fBdelim\fR, \fBheader\fR, and \fBcomment\fR.
There may be others as noted for individual prefabs.

.ig >>
<br><br><br>
.>>

.LP
\fBOUTPUT FILE NAMES\fR
.LP
The \fB-o\fR option may be used to specify output file name explicitly.
If \fB-o\fR is not given,
output file naming is similar to that of \fBpl\fR in other contexts.
For the above example the output file would be named \fCscat.png\fR .

.ig >>
<br><br><br>
.>>

.LP 
\fBCUSTOMIZATION\fR
.LP
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.

.LP
.ig >>
<a name=examples></a>
.>>
.ig >>
<br><br><br>
.>>
.LP
\fBEXAMPLES\fR
.LP
A number of examples are included for each prefab.
The command that was used to produce each one is shown (the
command line options \fC-gif -scale 0.7 -tightcrop\fR were also used
but are omitted for brevity).
All of the examples may be demonstrated by going to the 
prefabs directory (the command \fCecho $PLOTICUS_PREFABS\fR will show
the name of that directory), and entering the given command.


.ig >>
<br><br><br>
.>>
.LP
\fBHINTS\fR
.LP
The following 
.ig >>
<a href="pl.1.html#options">
.>>
\0pl command line options
.ig >>
</a>
.>>
may be very useful with prefabs:
\fC-scale\fR, \fC-color\fR, \fC-backcolor\fR, \fC-tightcrop\fR, and perhaps \fC-font\fR.
.LP
Be careful not to confuse prefab parameters with
.ig >>
<a href="pl.1.html#options">
.>>
\0pl command line options
.ig >>
</a>
.>>
\0.  Prefab parameters are given this way: \fCparamname=value\fR.
Command line options are given this way: \fC-option\fR or \fC-option value\fR.
.LP
Most shells allow a backslash (\\) for breaking up long commands into two or more lines.
.LP
You can get a multi line title by splitting it over two lines, eg:
.nf
    pl -prefab pie1 data=data1 fld=3 label=1 title="Travel expenditures
    By department
    Fiscal year 2000"
.fi

.ig >>
<br><br><br>
.>>

.ig >>
</td></tr>
<td>
<a name=std></a>
.>>

.ig >>
<br><br><br>
.>>

.SH STANDARD PARAMETERS FOR PREFABS
The following parameters are accepted by all prefabs unless otherwise stated.
The \fBdata\fR parameter is always required.  

.LP
\fBdata\fR 
.IP
Name of data file.  Always required.  May be given as \fC-\fR if data are to
be read from standard input.

.LP
\fBx\fR
.IP
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0Data field
.ig >>
</a>
.>>
to plot in X.  
Either a number (eg 2 for the 2nd field) or a name if a data file contains a header.

.LP
\fBy\fR
.IP
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0Data field
.ig >>
</a>
.>>
to plot in Y.
Either a number (eg 2 for the 2nd field) or a name if a data file contains a header.

.LP
\fBerr\fR
.IP
.ig >>
<a href="attributetypes.html#dfield">
.>>
\0Data field
.ig >>
</a>
.>>
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.

.LP
\fBtitle\fR
.IP
A plot title to be centered at the top.  The parameter \fBtitledet\fR is also available
for controlling 
.ig >>
<a href="textdetails.html">
.>>
\0details
.ig >>
</a>
.>>
of title placement and appearance.

.LP
\fBxlbl\fR
.IP
Label for X axis.  The parameter \fBxlbldet\fR is also available
for controlling
.ig >>
<a href="textdetails.html">
.>>
\0details
.ig >>
</a>
.>>
of X label placement and appearance.
For example, to adjust the label downward 8/10 inch:
\fC-xlbldet=adjust=0,-0.8\fR.

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

.LP
\fBxinc\fR
.IP
Increment amount for numeric X axis.

.LP
\fBxlog\fR
.IP
Logarithmic X axis.  Allowable values are \fClog\fR and \fClog+1\fR.

.LP
\fBxgrid\fR
.IP
If \fCyes\fR, vertical grid lines will be drawn at each X stub.  May also be specified as a
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
attribute.


.LP
\fBylbl\fR
.IP
Label for Y axis.  The parameter \fBylbldet\fR is also available
for controlling
.ig >>
<a href="textdetails.html">
.>>
\0details
.ig >>
</a>
.>>
of Y label placement and appearance.
For example, to adjust the label leftward 8/10 inch:
\fC-ylbldet=adjust=0,-0.8\fR.

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

.LP
\fByinc\fR
.IP
Increment amount for numeric Y axis.

.LP
\fBylog\fR
.IP
Logarithmic Y axis.  Allowable values are \fClog\fR and \fClog+1\fR.

.LP
\fBygrid\fR
.IP
If \fCyes\fR, horizontal grid lines will be drawn at each Y stub.  May also be specified as a
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
attribute.

.LP
\fBautow\fR
.IP
If \fCyes\fR, width of plotting area will be automatically determined by the data.

.LP
\fBstubvert\fR
.IP
If \fCyes\fR, X axis stubs will be rendered vertically.

.LP
\fBdelim\fR
.IP
Data file field delimitation method, either \fCspace\fR, \fCcomma\fR, or \fCtab\fR.  
\fCspace\fR is the default, and indicates that fields will be delimited on 
"white space".  See
.ig >>
<a href="dataformat.html">
.>>
\0data formats
.ig >>
</a>
.>>
for more information.

.LP
\fBheader\fR
.IP
\fCyes\fR if first non-comment line of data file contains field names.
These names may be used to reference the data fields.  Default is \fCno\fR.

.LP
\fBcomment\fR
.IP
Indicates data file comment character or symbol.
Default is \fC//\fR.

.LP
\fBselect\fR
.IP
A 
.ig >>
<a href="condex.html">
.>>
\0conditional expression
.ig >>
</a>
.>>
for selecting data records to include.
One at-sign should be used, not two.
Example: \fCselect="@1 = A"\fR

.LP
\fBinclude1\fR
.IP
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.

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


.ig >>
<br><br><br>
.>>

.SH USER-CONTRIBUTED PREFABS
User-contributed prefabs are welcome and may be sent to \fCsteve@sgpr.net\fR;
please include the prefab script file and a man page giving at least one working example.

.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="Welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
.>>
