## Standard prefab parameters

Version 2.32
Prefabs

Manual page for Standard_prefab_parameters(PL)

- Getting input data
- Controlling the plotting area and axes
- Legends
- Clickmaps and mouseover
- Including script code chunks

The following parameters are used with most prefabs. All parameters (except data) are generally optional.
Getting input data

Prefab parameter name | Data type | Default | Description | Examples (ignore line wrapping)
data | filename - | must be specified (unless `inlinedata` is used) | Specifies the name of your input data file. Use dash (-) for standard input. | `data=myfile.dat`
inlinedata | text |  | 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+) | `"inlinedata=A 3 B 7 C 5"`
delim | `space` or `tab` or `comma` | `space` | Data file field delimitation method. See data formats for more information. | `delim=tab`
header | `yes` or `no` | `no` | Should be specified as `yes` 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 `encodenames` below. | `header=yes`
comment | word | `//` | Indicates data file comment character or symbol. | `comment=#`
select | select expression |  | Selects which input data records to use based on a condition. (In this context one at-sign should be used, not two.) | `"select=@3 > 0.1"` (select all input records where field 3 is greater than 0.1)
echodata | `yes` or `no` | `no` | If `yes`, the data (as read and parsed) will be echoed to standard error as an aid to debugging. | `echodata=yes`
nfields | integer |  | Allows you to handle data sets where the number of fields per row varies, by imposing a uniform number of fields per row. | `nfields=8`

Controlling the plotting area and axes
Click here for terminology help

Prefab parameter name | Data type | Default | Description | Examples (ignore line wrapping)
title | text |  | A plot title to be centered at the top. Example: `"title=Amount of change, by sector"`
titledet | textdetails |  | Allows you to control details of title placement and appearance. Example: `"titledet= size=15 align=left"`
rectangle | x1 y1 x2 y2, in inches or cm. | varies | 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. Example: `"rectangle=2 2 8 5"`
autow | `yes` or `no` | `no` | If `yes`, the width of the plotting area will be automatically adjusted based on the data. Example: `autow=yes`
xlbl ylbl | text |  | Specify axis labels. Example: `"xlbl= Date of receipt"` You can also use eg. `xlbl=#usefname` to automatically present the X or Y data field name.
xlbldistance ylbldistance | inches or cm | 0.4" | The distance of the axis label from the axis.
xlbldet ylbldet | textdetails |  | Control details of axis label placement and appearance. Example: `"xlbldet= size=6 adjust=0,-0.8"` (adjust the X axis label downward 8/10 inch)

xrange
yrange

min [max]

based on data

Specify an explicit axis numeric range. If not specified, automatic scaling will be done. Usually two values, a min and a max. You can also generally specify one value, eg. `yrange=0` 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. (heatmap allows eg. `xrange=0` too).
Example: `"xrange= 0 22"`
Example: `"yrange= 120 170"`
Example: `yrange=0`
Example: `yrange=1400`
A chron example:
`"xrange= 01-jan-2003 28-feb-2003"`

xinc
yinc

incvalue [units]

based on data

Specify a numeric axis stub/tic 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 proc axis stubunits documentation for more info.)
Example: `yinc=50`
Example: `"yinc= 100 1000"` (put a stub every 100,000 w/ stubs in 000's)
Example: `"xinc= 1 month"` (put a stub for every month, chron prefab).

xnearest ynearest | value |  | May be used with automatic scaling to make the axis start and end on a round value boundary. More info. Example: `xnearest=100` (causes the X axis to start and end on an even multiple of 100). Example: `xnearest=month` (chron)
xlog ylog | `log` or `log+1` |  | If specified, the axis will be logarithmic. Example: `"ylog=log+1"`
xgrid ygrid | `yes` or linedetails |  | If specified, grid lines will be drawn. Example: `"xgrid= color=pink width=0.5"`
xstubfmt ystubfmt | formatspec | based on plot data type | Specifies a format for stubs. For numerics this is a printf-spec such as `%4.2f`. For dates/datetimes this is a displayable date format; for times it's a displayable time format. Old name: stubfmt.
xstubdet ystubdet | textdetails |  | Allows control over the size, location, color etc. of the stubs. Example: `"xstubdet= size=6 align=right"`
stubvert | `yes` or `no` | `no` | If `yes`, X axis stubs will be rendered vertically. Example: `stubvert=yes`
xaxis | `bottom` or `bottom,top` or `top` or `none` | `bottom` | Controls where X axis will be drawn (2.30+). `bottom` draws it along top of plotting area. `top` draws it along top of plotting area. `bottom,top` renders 2 Y axes, one at bottom and one at top. `none` suppresses the X axis completely. Example: `xaxis=bottom,top`
yaxis | `left` or `left,right` or `right` or `none` | `left` | Controls where Y axis will be drawn (2.30+). `left` draws it along left side of plotting area. `right` draws it along right side of plotting area. `left,right` renders 2 Y axes, one at left side and one at right side. `none` suppresses the Y axis completely. Example: `yaxis=none`

Legends
For many of the prefabs, a legend will be rendered if one or more name parameters are given,
or if using data set header fields. (The pie prefab operates differently.)

Prefab parameter name | Data type | Default | Description | Examples (ignore line wrapping)
name (name2.. 4) | one line text |  | Specifies legend label(s). Some prefabs also use name2, name3, name4 for multiple curves, plots, or bar sets. Example: `"name= Trial A" "name2= Trial B"`
legend | x y or `no` | varies | Controls the placement of the legend. Some prefabs also support `legend=no` to turn off the legend. Example: `legend=max+0.5 max` (places legend in upper-right corner)
legendfmt | `down` or `across` | `down` | Causes legend entries to be listed downward, or across. (Previous values of `multiline` and `singleline` are equivalent and will be supported indefinitely). Example: `legendfmt=across`
legtextdet | textdetails |  | Can be used to control appearance of legend text. New in 2.32. Example: `legtextdet="size=6"`
legwrap | nchars |  | If specified, legend labels will be wordwrapped to a max length of nchars. New in 2.32. Example: `legwrap=15`
legbreak | inches or cm |  | If specified, multi-column (or multi-row) legends are enabled. See proc legend extent attribute for how this operates. New in 2.32. Example: `legbreak=1.2`
legtitle | text |  | A title for the legend. New in 2.32. Example: `legtitle=Legend`
legbox | color |  | If specified, legend will have a backing box using this color. New in 2.32. Example: `legbox="gray(0.8)"`
legframe | `yes` or linedetails |  | If specified, legend will have a line frame. New in 2.32. Example: `legframe=yes`
legendsep | inches or cm | singleline: 1.2" multiline: 0" | (Discontinued) As of 2.32 this no longer does anything; new legend functionality should render it unnecessary. Example: `legendsep=0.5`

Pertaining to clickmap and mouseover
More info on clickmaps and mouseover

Prefab parameter name | Data type | Default | Description | Examples (ignore line wrapping)

clickmapurl

url template

A template for generating URLs when an HTML clickmap is being generated. The -map or -csmap command line option must be used in order to turn on clickmap generation. Bars (including those done using vbars, chron, and dist) scatterplot points (scat) and pie slice labels may be mapped. (Note: with the dist prefab, the label is in data field 1 and the count in field 2.)
Example: `clickmapurl: ?country=@1&n=@2`

clickmaplabel | text template |  | A template for generating mouseover text labels. The -map or -csmap command line option must be used in order to turn the feature on. Example: `clickmaplabel: @5`

Here's an example: Suppose `myfile.dat` 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:

      pl -prefab vbars  data=myfile.dat  delim=tab  y=1 \\
       clickmapurl="http://abc.com/cgi-bin/showcase?caseid=@2" \\
       clickmaplabel="@3"  -csmap -mapfile stdout

Including ploticus script code chunks for annotation, etc.

Prefab parameter name | Data type | Default | Description | Examples (ignore line wrapping)
include1 | filename |  | 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. Example: `include1=scriptchunk1.pl`
include2 | filename |  | Same as include1 except that the code is included after the data display is drawn. May be useful for adding annotation.

Misc

Prefab parameter name | Data type | Default | Description | Examples (ignore line wrapping)
enable_suscripts | `yes` or `no` | `yes` | Beginning in version 2.30 inline superscript and subscript support was added which involves using ^ to specify superscript content, and ` (grave accent) to specify subscript content. For convenience this is enabled in prefabs by default. If you need to use a literal ^ or ` in a title (etc.) you can turn this off by specifying: `enable_suscripts=no`

encodenames

`yes` or `no`

`yes`

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: `encodenames=no`

data display engine
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` August 23, 2005.