Ploticus > Prefabs >
Standard prefab parameters

These parameters can be used with most of the prefabs, to do standard things like getting input data, defining plotting area and axes. legends, clickmaps and mouseover, and other uses. All these parameters (except data) are generally optional. Don't forget that there are also pl(1) command line options that are useful for scaling, setting overall colors, and much more.

Getting input data

Data type DefaultDescription 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
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

[Terminology help]
Data type DefaultDescription 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

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.

inches or cm 0.4" The distance of the axis label from the axis.

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)

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"

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).

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)

  If specified, the axis will be logarithmic.
Example: "ylog=log+1"

  If specified, grid lines will be drawn.
Example: "xgrid= color=pink width=0.5"

min|max|minmax   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)
Example: "ygridskip=min"

color1 color2   Similar to a grid but produces alternating color background. (New in 2.41)
Example: "ygridblocks=gray(0.9) white"

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.

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
xstubround see proc axis stubround attribute    
firststub text   Allows the first stub (the one nearest the axis minima) to be specified explicitly, overriding what would automatically appear. Example: firststub=<0
laststub text   Allows the last stub (the one on or very near axis maxima) to be specified explicitly, overriding what would automatically appear. Example: laststub=24
xaxis bottom
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
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


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.)
Data type DefaultDescription Examples
(ignore line wrapping)

(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
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
Data type DefaultDescription 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="" \\
   clickmaplabel="@3"  -csmap -mapfile stdout

Including ploticus script code chunks for annotation, etc.

Data type DefaultDescription 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.
include2 filename   Same as include1 except that the code is included after the data display is drawn. May be useful for adding annotation.


Data type DefaultDescription 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


Ploticus 2.42 ... May 2013 Terms of use / GPL