.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: ploticus prefabs handbook</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>Ploticus Prefabs Handbook</h2></td>
  <td align=right>
  <small>
  <a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  Version 2.41 Mar2009
     </small><br><a href="../doc/prefabs.html">Prefabs</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH Ploticus_Prefabs_Handbook PL "11-MAR-2009   PL ploticus.sourceforge.net"

.LP
Prefabs offer an easy way to try ploticus...
there's no script file to create... command line args control everything.
Prefabs are meant for exploratory work and one-shot looks at data.
Flexibility is limited.  For production applications or projects needing any degree of customization,
.ig >>
<a href="scripthome.html">
.>>
\0ploticus scripts
.ig >>
</a>
.>>
are the recommended way to go, not prefabs.
Also, prefabs tend to be \fBsecond-tier\fR with regard to ongoing development and support.

.LP

.ig >>
The <a href="prefab_stdparms.html">standard prefab parameters</a> are common to most of the 
various prefabs and control things like reading in data, setting up axes, legends, and so on.
<br>
<br>
<b>Available prefabs:</b>
<ul>
<table cellpadding=2 border=1><tr>

<td><a href="prefab_chron.html"><img src="../gallery/prefab_img/chron7thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_chron.html">chron</a></font> - chronological data (dates, times, etc); also can tabulate on week, month, etc.
</td>

<td><a href="prefab_compare.html"><img src="../gallery/prefab_img/compare4thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_compare.html">compare</a></font> - convenient comparison of 1-4 vars across 1-15 categories.  Computes means and SD, and displays groups of bars.
<b>Currently suspended / unavailable</b>
</td>


<td><a href="prefab_cumufrac.html"><img src="../gallery/prefab_img/cumufrac2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_cumufrac.html">cumufrac</a></font> - cumulative fraction plots (linear or log)
</td>

</tr><tr>

<td><a href="prefab_dist.html"><img src="../gallery/prefab_img/dist1thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_dist.html">dist</a></font> - frequency distribution histogram, numeric or alphanumeric bins
</td>

<td><a href="prefab_heatmap.html"><img src="../gallery/prefab_img/heatmap2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_heatmap.html">heatmap</a></font> - heatmaps, density grids, and similar displays 
</td>

<td><a href="prefab_lines.html"><img src="../gallery/prefab_img/lines3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_lines.html">lines</a></font> - line plots with optional data points and error bars, up to 4 groups
</td>

</tr><tr>

<td><a href="prefab_pie.html"> <img src="../gallery/prefab_img/pie4thm.gif" border=0> </a><br>
<font size=+1>
<a href="prefab_pie.html">pie</a></font> - pie graphs
</td>

<td><a href="prefab_scat.html"><img src="../gallery/prefab_img/scat2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_scat.html">scat</a></font> - scatterplots, with optional regression line, point labeling, 
	and error bars, up to 4 groups
</td>

<td><a href="prefab_stack.html"><img src="../gallery/prefab_img/stack1thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_stack.html">stack</a></font> - stacked bar graphs up to 4 levels
</td>

</tr><tr>

<td><a href="prefab_stack.html"><img src="../gallery/prefab_img/stack3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_stack.html">stack</a></font> - also does stacked area plots
</td>

<td><a href="prefab_vbars.html"><img src="../gallery/prefab_img/vbars2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vbars.html">vbars</a></font> - bar graph of 1 or 2 groups with precomputed error bars
</td>

<td><a href="prefab_vbars.html"><img src="../gallery/prefab_img/vbars3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vbars.html">vbars</a></font> - also just the precomputed error bars 
</td>

</tr><tr>

<td><a href="prefab_vdist.html"><img src="../gallery/prefab_img/vdist1thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vdist.html">vdist</a></font> - bee swarm distribution of one variable.
</td>

<td><a href="prefab_vdist.html"><img src="../gallery/prefab_img/vdist3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vdist.html">vdist</a></font> - histogram comparison of two variables.
</td>

<td>&nbsp;</td>

</tr>
<tr><td colspan=3>
<li> <font size=+1><a href="prefab_draw.html">draw</a></font> 
	for processing drawdumps or ploticus draw commands
<li> <font size=+1><a href="prefab_multidist.html">multidist</a></font> 
	multiple overlaid frequency distributions
<li> <font size=+1><a href="prefab_processdata.html">processdata</a></font> 
	use ploticus as a data processing filter (no plots)
	<img src="../gallery/gif/new.gif">
</td></tr>
</table>

<br>
</ul>

<center>
<b><a href="prefab_gallery.html">Gallery of all prefab examples</a>

&nbsp; &nbsp; &nbsp;

<a href="prefab_news.html">What's new - prefabs</a></b>
<br>
<br>
<b><a href="prefab_stdparms.html">Summary of the standard prefab parameters</a></b>
</center>

<br><br>

<b>Quick start</b>
<ul>
1. <a href="download.html">Download the software</a> and install.
<br>
2. Set the <tt>PLOTICUS_PREFABS</tt> environment variable to the pathname of the ploticus <tt>./prefabs</tt> directory.
Be sure that the <tt>pl</tt> command is in your command search <tt>PATH</tt>.
<br>
3. Look at the <a href="prefab_gallery.html">prefab examples gallery</a> and find an example close to what you want.
<br>
4. Execute the pl command appearing below the example.
<br>
5. Check the <a href="prefab_stdparms.html">standard parameters</a> and the individual prefab manual page for
more possibilities.
<br>
6. Use prefabs as far as possible for prototyping and "quick-n-dirty" uses.. if you need "extreme" 
customization, use the <tt>-echo stdout</tt> commmand line option to dump out the equivalent
ploticus script, and go from there.
<br>
7. Overlay and/or combine multiple <tt>pl</tt> runs using <tt>-drawdump</tt> (see below)
</ul>

<br>

<b>The pl(1) command</b>
<ul>
<a href="pl.1.html">The pl(1) command</a>
is what you'll generally use to generate graphs.  
Use the <tt>-prefab</tt> command line option to select which prefab you want, eg: <tt>pl -prefab chron</tt>.
There are also options for specifying which output graphic format you want, and the output file name.
For instance, 
<center><b><tt>pl -prefab chron -png -o mygraph.png ...</tt></b></center>
There are a number of other command line options that are useful 
with prefabs, for scaling, setting overall colors, and much more.
<a href="pl.1.html">See the pl(1) manual page for more info</a>.
<p>
Note: pl command line options begin with a dash, but prefab parameters don't.
</ul>

<br>

<b>The PLOTICUS_PREFABS environment variable</b>
<ul>
must be set to the directory where prefab files are located.  Normally this is a
directory called <tt>./prefabs</tt> in the ploticus distribution.  
Note that, to avoid compatibility issues, the prefab files should be from the same ploticus version as the pl executable.
</ul>

<br>

<b>Prefab parameters</b> 
<ul>
control what prefabs do.  
Parameters are usually specified on the command line using the form <tt><i>parametername</i>=<i>value</i></tt>
but they may also (sometimes) be set
<a href="dataformat.html#set">from within an input data file</a> or in your <a href="config.html">ploticus config file</a>.
<p>
There are <a href="prefab_stdparms.html">standard prefab parameters</a>
which are parameters that are in common to most of the prefabs, and specify plot data fields, title, axes, 
data format, legends, and so on.  There are also parameters that are
specific to individual prefabs ... these are described on the individual prefab manual pages.
</ul>

<br>

<b>Commands and the shell</b>
<ul>
Ploticus prefab commands can get rather long.. most shells allow backslash for
continuing commands onto additional lines.
If a parameter value contains embedded whitespace the value should be enclosed in quotes.
You can get a multi line title by splitting it over multiple lines.  Here's an example:
<tt>
<br> &nbsp; &nbsp;
    pl -prefab pie1 data=data1 fld=3 label=1 &#92;
<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; 
title="Travel expenditures
<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
    By department
<br> &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
    Fiscal year 2000"
</tt>
</ul>

<br>

<b>Input data</b>
<ul>
Input data can come from files or standard input.
It should be plain ascii text.  Whitespace, tab, and comma delimited fields are supported.
You can plot various types of data including numeric, category, date, and time.
For date and time data, use the <a href="prefab_chron.html">chron prefab</a>.
</ul>

<a name=drawdump></a>
<br>
<b>Overlaying and combining plots from multiple pl runs</b>
<ul>
Beginning in version 2.30 you can use the <tt>-drawdump</tt> and <tt>-drawdumpa</tt> command line options 
to overlay and/or combine plots from multiple pl runs into one graphic image / result.  Example:
<ul>
<tt>
pl -prefab scat "rectangle= 1 1 3 3" .... -drawdump mydump <br>
pl -prefab scat "rectangle= 4 1 6 3" .... -drawdumpa mydump <br>
pl -prefab draw dumpfile=mydump  -png -o all.png
</tt>
</ul>
<br>
Hints:
<br>
<li> if you're setting a background color this should be done only in the first <tt>pl</tt> invocation.
<li> for overlays using the same plotting area rectangle and scaling, turn off axis generation (<tt>xaxis=none yaxis=none</tt>).
<li> for overlays using same plotting area rectangle and different scaling, use eg. <tt>yaxis=left</tt> for one and <tt>yaxis=right</tt> for the other.
<li> clickmap/mouseover info is not retained in drawdump file, but can be generated by individual pl invocation for PNG (etc.)
<li> you can get a graphic result while generating a drawdump.. just specify the device argument somewhere to the right of
the -drawdump <i>filename</i> argument on the command line.
</ul>
<br>

<b>Customizing</b>
<ul>
It is possible to include chunks of ploticus script code to add annotations, etc.
(see the standard parameters <a href="prefab_stdparms.html#include">include1 and include2</a>).
Otherwise, for needs that aren't addressed by existing prefabs, you can develop a ploticus script.
Get as far as you can with the prefab, then use the 
<tt>-echo stdout</tt> option to dump out an equivalent script.. then modify the script as needed.
</ul>

<br>
<b>Notes</b>
<ul>
<li> No error message is issued when an invalid prefab parameter name is used.
</ul>
<br>


<h3>Reference</h3>
<ul>
<br><a href="dataformat.html">Input data for plotting</a>
<br><a href="scaleunits.html">Data types and scaling: numeric, category, date, time</a>
<br><a href="attributetypes.html">Absolute units, scaled units, etc.</a>
<br><a href="attributetypes.html#n">Attribute types: dfield, plotvalue, locvalue, printf, string, text, multilinetext</a>
<br><a href="linedetails.html">Linedetails</a>
<br><a href="symboldetails.html">Symboldetails</a>
<br><a href="textdetails.html">Textdetails</a>
<br><a href="select.html">Select expressions</a>
<br><a href="color.html">Colors</a>
<br><a href="fonts.html">Fonts</a>
<br><a href="dates.html">Dates</a>
<br><a href="times.html">Times</a>
<br><a href="config.html">Your ploticus config file - settings to be in effect all the time</a>
<br>
<br><a href="news.html">What's new - general</a> 
<br><a href="prefab_news.html">What's new - prefabs</a>
<br><a href="faq.html">FAQ</a>
<br><a href="http://groups.yahoo.com/group/ploticus">Newsgroup</a>
<br><a href="pl.1.html">pl(1) man page</a>
<br><a href="api.html">libploticus API</a>

<br><a href="web.html">Web usage notes</a>
<br><a href="clickmap.html">Imagemap, clickmap & mouseover text bubbles</a>
<br><a href="dynamic.html">Dynamic content and just-in-time usage notes</a>
<br><a href="cgi.html">Direct CGI mode</a>
<br><a href="paper.html">Paper-based report usage notes</a>
<br><a href="posters.html">Large-sized poster usage notes</a>
<br><a href="prepress.html">Pre-press work usage notes</a>
<br><a href="svg.html">SVG notes</a> 
<br><a href="swf.html">SWF (shockwave-flash) notes</a>

<br><a href="http://ploticus.sourceforge.net/doc/download.html">Download</a>
<br><a href="buildinfo.html">Build instructions</a>
<br><a href="support.html">Troubleshooting & support</a>
<br><a href="limits.html">Limitations</a>
<br><a href="Copyright.html">Copyright and permissions <img src="../doc/gpl.gif" border=0></a>
<br><a href="http://ploticus.sourceforge.net/steve.html">Steve Grubb's home page</a>

</ul>

<br>
<b><a href="welcome.html">Back to ploticus home</a></b>
<br><br>
<b><a href="scripthome.html">Ploticus scripts handbook</a></b>

<br>

.>>

.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>
<br>
<center>
<table><tr><td>
Ploticus is hosted at http://ploticus.sourceforge.net</td><td> &nbsp; </td><td>
<a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12" 
width="120" height="30" border="0" 
alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td></tr></table>


</center>
.>>
