<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/11/09 12:56:20. -->
<!-- Do not edit! -->
<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: standard prefab parameters</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>Standard prefab parameters</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>
<title>Manual page for Standard_prefab_parameters(PL)</title>
</head>
<body>
<center>
<table cellpadding=2 bgcolor=FFFFEC><tr><td>
<li> <a href=#getdata>Getting input data</a>
<li> <a href=#plottingarea>Controlling the plotting area and axes</a>
<li> <a href=#legend>Legends</a>
<li> <a href=#clickmap>Clickmaps and mouseover</a>
<li> <a href=#include>Including script code chunks</a>
</td></tr></table></center>
<br>
<br>
The following parameters are used with most <a href="prefabs.html">prefabs</a>.
All parameters (except <b>data</b>) are generally optional.
Don't forget that there are also
<a href="pl.1.html">pl(1) command line options</a> that are useful
for scaling, setting overall colors, and much more.
<br>
<br>
<br>
<br>
<a name=getdata></a>
<font size=+1><b>Getting input data</b></font>
<table cellpadding=2 width=600 bgcolor=A0A0A0>
<tr bgcolor=FFFFEC align=center><td><b>Prefab<br>parameter<br>name</td><td>Data type</td>
<td>Default</td><td>Description</td>
<td>Examples<br><small>(ignore line wrapping)</td></tr>
<tr bgcolor=FFFFFF>
<td><b>data</td>
<td><i>filename</i><br>-</td>
<td><font color=D00000>must be specified</font> (unless <tt>inlinedata</tt> is used)</td>
<td>Specifies the name of your input data file. Use dash (-) for standard input.</td>
<td><tt>data=myfile.dat</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>inlinedata</td>
<td>text</td>
<td> </td>
<td>This allows a small amount of data (< 255 chars) to be specified directly on the command line.
Data rows should be delimited by newlines as seen at right (don't ignore!).
(2.30+)
</td>
<td><tt>"inlinedata=A 3<br>
B 7 <br>
C 5"</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>delim</td>
<td><tt>space</tt><br>or<br><tt>tab</tt><br>or<br><tt>comma</td>
<td><tt>space</tt></td>
<td>Data file field delimitation method. See <a href="dataformat.html">data formats</a> for more information.</td>
<td><tt>delim=tab</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>header</td>
<td><tt>yes</tt> or <tt>no</tt></td>
<td><tt>no</tt></td>
<td>Should be specified as <tt>yes</tt> if the first non-comment line of data file contains field names.
These names may then be used to reference data fields.
Field names cannot contain spaces or commas directly, but see <tt>encodenames</tt> below.
</td>
<td><tt>header=yes</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>comment</td>
<td>word</td>
<td><tt>//</td>
<td>Indicates data file comment character or symbol.</td>
<td><tt>comment=#</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>select</td>
<td><a href="select.html">select expression</td>
<td> </td>
<td>Selects which input data records to use based on a condition. (In this context one at-sign should be used, not two.)</td>
<td><tt>"select=@3 > 0.1"</tt><br>(select all input records where field 3 is greater than 0.1)</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>echodata</td>
<td><tt>yes</tt> or <tt>no</tt></td>
<td><tt>no</td>
<td>If <tt>yes</tt>, the data (as read and parsed) will be echoed
to standard error as an aid to debugging.</td>
<td><tt>echodata=yes</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>nfields</td>
<td>integer</td>
<td> </td>
<td>Allows you to handle data sets where the number of fields per row varies, by
imposing a uniform number of fields per row.</td>
<td><tt>nfields=8</td>
</tt>
</table>
<br>
<br>
<br>
<a name=plottingarea></a>
<font size=+1><b>Controlling the plotting area and axes</b></font>
<br><a href="../gallery/simple2annot.gif">Click here for terminology help</a>
<table cellpadding=2 width=600 bgcolor=A0A0A0>
<tr bgcolor=FFFFEC align=center><td><b>Prefab<br>parameter<br>name</td><td>Data type</td>
<td>Default</td><td>Description</td>
<td>Examples<br><small>(ignore line wrapping)</td></tr>
<tr bgcolor=FFFFFF>
<td><b>title</td>
<td><i>text</td>
<td> </td>
<td colspan=2>A plot title to be centered at the top.<br>
Example: <tt>"title=Amount of change, by sector"</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>titledet</td>
<td><a href="textdetails.html">textdetails</td>
<td> </td>
<td colspan=2>Allows you to control details of title placement and appearance.<br>
Example: <tt>"titledet= size=15 align=left"</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>rectangle</td>
<td><i>x1 y1 x2 y2</i>, in <a href="atypes.html#punits">inches or cm</a>.</td>
<td>varies</td>
<td colspan=2>Specify the dimensions of the plotting area.
x1 and y1 are the coordinates of the lower-left corner of the rectangle, and
x2 and y2 are the coordinates of the upper-right corner.<br>
Example: <tt>"rectangle=2 2 8 5"</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>autow</td>
<td><tt>yes</tt> or <tt>no</tt></td>
<td><tt>no</td>
<td colspan=2>If <tt>yes</tt>, the width of the plotting area will be automatically adjusted based on the data.<br>
Example: <tt>autow=yes</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xlbl<br><br>ylbl</b></td>
<td><i>text</i></td>
<td> </td>
<td colspan=2>Specify <a href="../gallery/simple2annot.gif">axis labels</a>.<br>
Example: <tt>"xlbl= Date of receipt"</tt><br>
You can also use eg. <tt>xlbl=#usefname</tt> to automatically present the X or Y data field name.</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xlbldistance<br><br>ylbldistance</b></td>
<td>inches or cm</td>
<td>0.4"</td>
<td colspan=2>The distance of the <a href="../gallery/simple2annot.gif">axis label</a> from the axis.</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xlbldet<br><br>ylbldet</b></td>
<td><a href="textdetails.html">textdetails</td>
<td> </td>
<td colspan=2>Control details of <a href="../gallery/simple2annot.gif">axis label</a> placement and appearance.<br>
Example: <tt>"xlbldet= size=6 adjust=0,-0.8"</tt><br> (adjust the X axis label downward 8/10 inch)</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xrange<br><br>yrange</b></td>
<td><i>min [max]</td>
<td>based on data</td>
<td colspan=2>Specify an explicit axis numeric range. If not specified, automatic scaling
will be done. Usually two values, a <i>min</i> and a <i>max</i>.
You can also generally specify one value, eg. <tt>yrange=0</tt> which allows you to specify the minima (0 in this case)
and have an automatically determined maxima. Any data values < the specified minima will override it.
(<b>heatmap</b> allows eg. <tt>xrange=0</tt> too).<br>
Example: <tt>"xrange= 0 22"</tt><br>
Example: <tt>"yrange= 120 170"</tt><br>
Example: <tt>yrange=0</tt><br>
Example: <tt>yrange=1400</tt><br>
A chron example:<br><tt>"xrange= 01-jan-2003 28-feb-2003"</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xinc<br><br>yinc</td>
<td><nobr><i>incvalue [units]</td>
<td>based on data</td>
<td colspan=2>
Specify a numeric axis <a href="../gallery/simple2annot.gif">stub/tic</a>
increment amount. Normally one value.
It is also possible to supply two values, in which case the second
will be taken as the units (see <a href="axis.html#stubunits">proc axis stubunits</a>
documentation for more info.)<br>
Example: <tt>yinc=50</tt><br>
Example: <tt>"yinc= 100 1000"</tt> (put a stub every 100,000 w/ stubs in 000's)<br>
Example: <tt>"xinc= 1 month"</tt> (put a stub for every month, chron prefab).
</td></tr>
<tr bgcolor=FFFFFF>
<td><b>xnearest<br><br>ynearest</td>
<td><i>value</i></td>
<td> </td>
<td colspan=2>May be used with automatic scaling to make the axis start and end on a round value boundary.
<a href="autorange.html#nearest">More info</a>.<br>
Example: <tt>xnearest=100</tt> (causes the X axis to start and end on an even multiple of 100).
<br>
Example: <tt>xnearest=month</tt> (chron)
</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xlog<br><br>ylog</td>
<td><tt>log</tt><br>or<br><tt>log+1</tt>
<td> </td>
<td colspan=2>If specified, the axis will be logarithmic.<br>
Example: <tt>"ylog=log+1"</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xgrid<br><br>ygrid</td>
<td><tt>yes</tt><br>or<br><a href="linedetails.html">linedetails</a></td>
<td> </td>
<td colspan=2>If specified, grid lines will be drawn.<br>
Example: <tt>"xgrid= color=pink width=0.5"</tt>
</td></tr>
<tr bgcolor=FFFFFF>
<td><b>xgridskip<br><br>ygridskip</td>
<td><tt>min|max|minmax</tt></td>
<td> </td>
<td colspan=2>Sometimes grid lines will obscure axis line giving undesired result.
Use this parameter to eliminate grid line at the minima (min) or maxima (max) or both (minmax). (New in 2.41)<br>
Example: <tt>"ygridskip=min"</tt>
</td></tr>
<tr bgcolor=FFFFFF>
<td><b>xgridblocks<br><br>ygridblocs</td>
<td>color1 color2</td>
<td> </td>
<td colspan=2>Similar to a grid but produces alternating color background. (New in 2.41)<br>
Example: <tt>"ygridblocks=gray(0.9) white"</tt>
</td></tr>
<tr bgcolor=FFFFFF>
<td><b>xstubfmt<br><br>ystubfmt</td>
<td><i>formatspec</td>
<td>based on plot data type</td>
<td colspan=2>Specifies a format for
<a href="../gallery/simple2annot.gif">stubs</a>.
For numerics this is a <a href="atypes.html#printfspec">printf-spec</a>
such as <tt>%4.2f</tt>. For dates/datetimes this is a <a href="dates.html">displayable date format</a>; for times it's a
<a href="times.html">displayable time format</a>.
Old name: <b>stubfmt</b>.</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xstubdet<br><br>ystubdet</td>
<td><a href="textdetails.html">textdetails</a></td>
<td> </td>
<td colspan=2>Allows control over the size, location, color etc. of the <a href="../gallery/simple2annot.gif">stubs</a>.<br>
Example: <tt>"xstubdet= size=6 align=right"</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>stubvert</td>
<td><tt>yes</tt> or <tt>no</tt></td>
<td><tt>no</td>
<td colspan=2>If <tt>yes</tt>, X axis <a href="../gallery/simple2annot.gif">stubs</a>
will be rendered vertically.<br>
Example: <tt>stubvert=yes</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>firststub</td>
<td><i>text</i></td>
<td> </td>
<td colspan=2>
Allows the first stub (the one nearest the axis minima) to be specified explicitly, overriding what would automatically appear.
Example: <tt>firststub=<0</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>laststub</td>
<td><i>text</i></td>
<td> </td>
<td colspan=2>
Allows the last stub (the one on or very near axis maxima) to be specified explicitly, overriding what would automatically appear.
Example: <tt>laststub=24</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>xaxis</td>
<td>
<tt>bottom</tt><br>or<br><tt>bottom,top</tt><br>or<br><tt>top</tt><br>or<br><tt>none</tt></td>
<td><tt>bottom</td>
<td colspan=2>Controls where X axis will be drawn (2.30+).<br>
<tt>bottom</tt> draws it along top of plotting area.<br>
<tt>top</tt> draws it along top of plotting area.<br>
<tt>bottom,top</tt> renders 2 Y axes, one at bottom and one at top.
<tt>none</tt> suppresses the X axis completely.<br>
Example: <tt>xaxis=bottom,top</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>yaxis</td>
<td><tt>left</tt><br>or<br><tt>left,right</tt><br>or<br><tt>right</tt><br>or<br><tt>none</tt></td>
<td><tt>left</td>
<td colspan=2>Controls where Y axis will be drawn (2.30+).<br>
<tt>left</tt> draws it along left side of plotting area.<br>
<tt>right</tt> draws it along right side of plotting area.<br>
<tt>left,right</tt> renders 2 Y axes, one at left side and one at right side.
<tt>none</tt> suppresses the Y axis completely.<br>
Example: <tt>yaxis=none</td>
</tr>
</table>
<br>
<br>
<br>
<a name=legend></a>
<font size=+1><b>Legends</b></font><br>
For many of the prefabs, a legend will be rendered if one or more <b>name</b> parameters are given,<br>
or if using data set header fields. (The <a href="prefab_pie.html">pie prefab</a> operates differently.)
<table cellpadding=2 width=600 bgcolor=A0A0A0>
<tr bgcolor=FFFFEC align=center><td><b>Prefab<br>parameter<br>name</td><td>Data type</td>
<td>Default</td><td>Description</td>
<td>Examples<br><small>(ignore line wrapping)</td></tr>
<tr bgcolor=FFFFFF>
<td><nobr><b>name<br><br>(name2.. 4)</td>
<td><i>one line text</td>
<td> </td>
<td colspan=2>Specifies legend label(s).
Some prefabs also use <b>name2</b>, <b>name3</b>, <b>name4</b>
for multiple curves, plots, or bar sets.<br>
Example: <tt>"name= Trial A" "name2= Trial B"</tt>
</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legend</b></td>
<td><a href="atypes.html#xy">x y</a>
<br>or <tt>no</td>
<td>varies</td>
<td colspan=2>Controls the placement of the legend.
Some prefabs also support <tt>legend=no</tt> to turn off the legend.<br>
Example: <tt>legend=max+0.5 max</tt> (places legend in upper-right corner)</td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legendfmt</td>
<td><tt>down</tt><br>or<br><tt>across</td>
<td><tt>down</td>
<td colspan=2>Causes legend entries to be listed downward, or across.
(Previous values of <tt>multiline</tt> and <tt>singleline</tt> are equivalent and will
be supported indefinitely).
Example: <tt>legendfmt=across</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legtextdet</td>
<td><a href="textdetails.html">textdetails</a></td>
<td> </td>
<td colspan=2>Can be used to control appearance of legend text. New in 2.32.<br>
Example: <tt>legtextdet="size=6"</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legwrap</td>
<td>nchars</td>
<td> </td>
<td colspan=2>If specified, legend labels will be wordwrapped to a max length of nchars.
New in 2.32.<br>
Example: <tt>legwrap=15</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legbreak</td>
<td>inches or cm</td>
<td> </td>
<td colspan=2>If specified, multi-column (or multi-row) legends are enabled.
See <a href="legend.html">proc legend extent attribute</a> for how this operates.
New in 2.32.<br>
Example: <tt>legbreak=1.2</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legtitle</td>
<td>text</td>
<td> </td>
<td colspan=2>A title for the legend. New in 2.32.<br>
Example: <tt>legtitle=Legend</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legbox</td>
<td><a href="color.html">color</a></td>
<td> </td>
<td colspan=2>If specified, legend will have a backing box using this color. New in 2.32.<br>
Example: <tt>legbox="gray(0.8)"</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legframe</td>
<td><tt>yes</tt> or <a href="linedetails.html">linedetails</a></td>
<td> </td>
<td colspan=2>If specified, legend will have a line frame. New in 2.32.<br>
Example: <tt>legframe=yes</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>legendsep</td>
<td><a href="atypes.html#punits">inches or cm</a></td>
<td>singleline: 1.2"<br>multiline: 0"</td>
<td colspan=2>(Discontinued) As of 2.32 this no longer does anything;
new legend functionality should render it unnecessary.
<br>
Example: <tt>legendsep=0.5</tt></td>
</tr>
</table>
<br>
<br>
<br>
<a name=clickmap></a>
<font size=+1><b>Pertaining to clickmap and mouseover</b></font><br>
<a href="clickmap.html">More info on clickmaps and mouseover</a>
<table cellpadding=2 width=600 bgcolor=A0A0A0>
<tr bgcolor=FFFFEC align=center><td><b>Prefab<br>parameter<br>name</td><td>Data type</td>
<td>Default</td><td>Description</td>
<td>Examples<br><small>(ignore line wrapping)</td></tr>
<tr bgcolor=FFFFFF>
<td><b>clickmapurl</td>
<td>url template</td>
<td> </td>
<td colspan=2>A template for generating URLs when an <a href="clickmap.html">HTML clickmap</a>
is being generated.
The <b>-map</b> or <b>-csmap</b> command line option must be
used in order to turn on clickmap generation.
Bars (including those done using <a href="prefab_vbars.html">vbars</a>,
<a href="prefab_chron.html">chron</a>, and
<a href="prefab_dist.html">dist</a>)
scatterplot points (<a href="prefab_scat.html">scat</a>) and
<a href="prefab_pie.html">pie slice labels</a> may be mapped.
(Note: with the <a href="prefab_dist.html">dist prefab</a>, the label is in data field 1 and the
count in field 2.)<br>
Example: <tt>clickmapurl: ?country=@1&n=@2</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>clickmaplabel</td>
<td>text template</td>
<td> </td>
<td colspan=2>A template for generating mouseover text labels.
The <b>-map</b> or <b>-csmap</b> command line option must be used in order to turn the feature on.<br>
Example: <tt>clickmaplabel: @5</td>
</tr>
<tr bgcolor=FFFFFF>
<td colspan=5>
Here's an example: Suppose <tt>myfile.dat</tt> has values in field 1, case IDs in field 2, and descriptive strings
in field 3. Assume that we have a URL that accepts case IDs as a user variable. We could generate a bar graph
with click-thru and mouseover popup text bubble support by using this command:
<pre>
pl -prefab vbars data=myfile.dat delim=tab y=1 \\
clickmapurl="http://abc.com/cgi-bin/showcase?caseid=@2" \\
clickmaplabel="@3" -csmap -mapfile stdout
</pre>
</td></tr>
</table>
<br>
<br>
<br>
<a name=include></a>
<font size=+1><b>Including ploticus script code chunks for annotation, etc.</b></font><br>
<table cellpadding=2 width=600 bgcolor=A0A0A0>
<tr bgcolor=FFFFEC align=center><td><b>Prefab<br>parameter<br>name</td><td>Data type</td>
<td>Default</td><td>Description</td>
<td>Examples<br><small>(ignore line wrapping)</td></tr>
<tr bgcolor=FFFFFF>
<td><b>include1</td>
<td>filename</td>
<td> </td>
<td colspan=2>Specifies a file containing <a href="scripthome.html">ploticus script code</a>.
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.<br>
Example: <tt>include1=scriptchunk1.pl</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>include2</td>
<td>filename</td>
<td> </td>
<td colspan=2>Same as <b>include1</b> except that
the code is included after the data display is
drawn. May be useful for adding annotation.
</td>
</tr>
</table>
<br>
<br>
<br>
<a name=misc></a>
<font size=+1><b>Misc</b></font><br>
<table cellpadding=2 width=600 bgcolor=A0A0A0>
<tr bgcolor=FFFFEC align=center><td><b>Prefab<br>parameter<br>name</td><td>Data type</td>
<td>Default</td><td>Description</td>
<td>Examples<br><small>(ignore line wrapping)</td></tr>
<tr bgcolor=FFFFFF>
<td><b>enable_suscripts</td>
<td><nobr><tt>yes</tt> or <tt>no</td>
<td><tt>yes</td>
<td colspan=2>
Beginning in version 2.30
<a href="fonts.html">inline superscript and subscript support</a> was added which
involves using <b>^</b> to specify superscript content, and <b>`</b> (grave accent) to specify subscript content.
For convenience this is enabled in prefabs by default.
If you need to use a literal <b>^</b> or <b>`</b> in a title (etc.) you can turn this off
by specifying: <tt>enable_suscripts=no</tt></td>
</tr>
<tr bgcolor=FFFFFF>
<td><b>encodenames</td>
<td><nobr><tt>yes</tt> or <tt>no</td>
<td><tt>yes</td>
<td colspan=2>
Beginning in version 2.30 a feature (proc settings encodenames) was added whereby
spaces and commas could be represented in field names using underscore (_) and bar (|) respectively.
This is useful for example when field names will be displayed directly in legends.
Since prefabs often do this, this feature is enabled for prefabs, by default.
To turn this off use: <tt>encodenames=no</tt></td>
</tr>
</table>
<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 <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> </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>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009.
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ed05dc5f357c49fdded780f52b150dce
>
files
>
92
