.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 "13-JUN-2002   PL ploticus.sourceforge.net"

.SH Available prefabs
.ig >>
<table cellpadding=2 border=1><tr>
<td><a href="prefab_chron.html"><img src="../gallery/prefab_img/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="../gallery/prefab_img/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="../gallery/prefab_img/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="../gallery/prefab_img/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="../gallery/prefab_img/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="../gallery/prefab_img/scat2thm.gif" border=0></a><br>
<a href="prefab_scat.html">scat</a> - scatterplots 
</td>
<td><a href="prefab_vbars.html"><img src="../gallery/prefab_img/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="../gallery/prefab_img/vbars3thm.gif" border=0></a><br>
<a href="prefab_vbars.html">vbars</a> - with error bars only
</td>
</tr>
</table>
<br>
.>>
.LP
Also available:
.IP \(bu
.ig >>
<a href="prefab_draw.html">
.>>
\0draw
.ig >>
</a>
.>>
for interpreting ploticus draw commands
.IP \(bu
.ig >>
<a href="prefab_multidist.html">
.>>
\0multidist
.ig >>
</a>
.>>
user-contributed prefab that does multiple, overlaid frequency distributions.

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

.SH What are prefabs?
Prefabs are the easiest way to get started with ploticus.
You can quickly generate common types of plots without needing to code a ploticus script.
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

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

.SH What do I need to do before I begin?
Prefabs work by invoking special ploticus scripts that have been generalized
to accept various parameters.  
These scripts are included with ploticus in the \fC./prefabs\fR directory.
You can use this directory or set up one of your own.
So that ploticus can find these files,
you must supply the full path name of the directory in an environment variable called \fBPLOTICUS_PREFABS\fR
(alternatively this may be hard-coded at build time, settable in the Makefile as \fBPREFABS_DIR\fR).

.ig >>
<br><br><br>
.>>
.SH Which parts of the ploticus documentation do I need to look at?
Prefab users should find most of what they need to know from this page along with
the first three sections of the
.ig >>
<a href="Contents.html">
.>>
\0ploticus handbook.
.ig >>
</a>
.>>
Prefabs are a higher-level interface to the functionality available in scripts, so there may
be an occational need to jump into the other documentation for certain particulars.

.ig >>
<br><br><br>
.>>
.SH Will I outgrow prefabs?
Prefabs are intended to cover common, straightforward situations.
By their very nature, prefabs do not offer the flexibility that's available
with scripts.  If you work with prefabs for a while you will probably encounter
something that you can't do with prefabs, but could do with a script.  
At this point I recommend making the jump to script coding; it's not really 
that hard if you learn by looking at the examples.


.ig >>
<br><br><br>
.>>
.SH Passing parameters to a prefab
.LP
Parameters may be supplied on the \fBpl\fR command line as \fIvar=value\fR
pairs as seen in the above example. 
There is a set of
.ig >>
<a href="prefab_stdparms.html">
.>>
\0standard parameters
.ig >>
</a>
.>>
that are recognized by all the prefabs unless otherwise noted; it is useful to become familiar with these.
Individual prefabs also have parameters of their own.
.LP
If convenient, most parameters may 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 \fCdata\fR, \fCdelim\fR, \fCheader\fR, and \fCcomment\fR.
There may be others as noted for individual prefabs.

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

.SH Output file names
.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>
.>>
.SH Plot data
Plot data must be located in a file.
The name of the data file is given in the 
.ig >>
<a href="prefab_stdparms.html">
.>>
\0data= parameter
.ig >>
</a>
.>>
the data field delimitation method may be given in the 
.ig >>
<a href="prefab_stdparms.html">
.>>
\0delim= parameter
.ig >>
</a>
.>>
\0.  See 
.ig >>
<a href="dataformat.html">
.>>
\0dataformat
.ig >>
</a>
.>>
for more information on acceptable data formats.
Missing data fields are generally skipped, but this depends
on what kind of plot is being generated. See
.ig >>
<a href="dataformat.html">
.>>
\0dataformat
.ig >>
</a>
.>>
for more discussion of missing data.

.ig >>
<br><br><br>
.>>
.SH Customization
.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
If you just want different defaults for a prefab, you can create a shell script
that invokes the prefab as you want it.  Then, 
put a \fC$*\fR at the end of the pl
command to pick up any overrides that the shell script user enters
on the command line (if a parameter is given twice, the rightmost is taken).

.LP
.ig >>
<a name=examples></a>
.>>
.ig >>
<br><br><br>
.>>
.SH Examples
.LP
All prefab examples are included in the ploticus test suite that is included
with all distributions (2.02 and later).


.ig >>
<br><br><br>
.>>
.SH Hints
You can create a 
.ig >>
<a href="config.html">
.>>
\0ploticus config file
.ig >>
</a>
.>>
and use it to set prefab parameters that you always want to be in effect.
For example:
.nf
   option:  comment=#  
   option:  delim=comma
.fi

.LP
It is possible to set parameters from within your data file using 
.ig >>
<a href="dataformat.html#set">
.>>
\0embedded #set statements.
.ig >>
</a>
.>>

.LP
The following 
.ig >>
<a href="pl.1.html#options">
.>>
\0pl command line options
.ig >>
</a>
.>>
may be very useful with prefabs:
\fB-scale\fR, \fB-color\fR, \fB-backcolor\fR, \fB-tightcrop\fR, \fB-map\fR,
\fB-debug\fR,
and perhaps \fB-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

.LP
.ig >>
<a href="clickmap.html">
.>>
\0HTML clickmaps
.ig >>
</a>
.>>
may be generated using the prefab 
.ig >>
<a href="prefab_stdparms.html#clickmapurl">
.>>
\0clickmapurl standard parameter
.ig >>
</a>
.>>
\0.

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

.SH User-contributed prefabs
User-contributed prefabs are welcome and may be sent to \fCscg@jax.org\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="../doc/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>
.>>
