Search


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

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

[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"
xgridskip ygridskip	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"
xgridblocks ygridblocs	color1 color2		Similar to a grid but produces alternating color background. (New in 2.41) Example: "ygridblocks=gray(0.9) white"
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
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 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