FAQ - frequently asked questions
Version 2.42 May2013
Some basic introductory questions are now addressed on the
ploticus home page.
Is there an interactive mode?
No, the main thrust has been to develop an engine
that can produce graphics non-interactively, so that
it can be run in an automated, unattended way.
What is ploticus good for?
Ploticus is good at making the types of 2-D graphs that you would see in
journals for medical and social sciences,
newspapers and news magazines, business publications, and so on.
Ploticus is good for automated or just-in-time graph generation, handles date and time
data nicely, and has basic statistical capabilities. It allows significant user control
over colors, styles, options and details.
What is ploticus not good for?
Ploticus is not a function plotting package; it has scant support for
mathematical formulas, scientific notations, or inline font or point size changes.
You can't plot binary data with ploticus.
There are no 3-D types of plots such as contours.
Ploticus is not a "marketing" graphics package, and
"chartjunk" effects, clip-art, gradient backgrounds, and so on have been intentionally avoided.
I see there are two possible approaches: prefabs vs. scripts. Compare and contrast?
If I start out using prefabs will it be difficult to transition to scripts?
For both approaches you use the
(or C programmers can use the
For prefabs you use pl -prefab prefabname ... and for scripts you use
pl scriptfile ...
Prefabs are easier because all parameters are given on the command line.. everything else
uses reasonable (?) defaults. The new -drawdump functionality makes prefabs more
powerful by allowing you to combine/overlay multiple pl runs into one graphic result.
Scripts are a lot more flexible but there's a bigger learning curve.
A recommended approach is to begin by prototyping with prefabs, then use the -echo stdout option to
dump out an equivalent script, then work from there. This helps with transitioning from one to the other.
Prefabs are really just special, generalized scripts that can accept a lot of parameters.. but because of
this the prefab scripts should not really be the place where you learn how to write scripts.
Is a "config file" the same thing as a "script file"?
No! They are two different things! If you think they're the same thing you will be confused
everywhere in the documentation! Here's the difference: You create a
to tell ploticus how to draw a particular graph (axes, title, reading the data, plotting).
On the other hand, you can create a
(if you want to) in order to get certain "environmental" settings in effect every time you run pl,
such as a default date format, international number notation or month names, and so on. You can also the
config file option directive to automatically set any
pl command line option
every time you run pl.
What statistical capabilities does ploticus include?
Some. There are capabilities for curve fitting,
computing linear regression, and Pearson correlation coefficient r.
There is a built-in facility (proc tabulate) for computing frequency
distributions. Means, medians, quartiles, standard deviations, etc. may
be computed using proc processdata or proc rangebar.
It would be nice if I could have ploticus process/manipulate my data so I don't have to invoke another program
to do this.
Script writers can do a number of manipulations using
These capabilities are worth becoming familiar with.
Script writers can alter the format of the data on a row by row basis by using
proc getdata's filter attribute.
If you just need to select certain rows from a data set, you can do this using select
attribute when data are read, or when rendering a certain plot.
Can I use ploticus as part of a commercial package or service?
Can ploticus get data directly from MySQL, Oracle, Excel, Access, etc.?
Ploticus is not tightly integrated with these other environments.
You would need to dump data out into an ascii file first, or pipe the data and tell ploticus
to read from standard input.
Script writers can also invoke a shell command which generates data, such as this:
command: mysql ...
What about large data sets?
are fairly large, and you can increase most of them using
command line capacity-setting arguments.
Another thing to consider (in scripts) is using
select or filter attributes to pare down the size as the data are being read.
Can I import ploticus graphs into PowerPoint, Word, etc.?
PNG and GIF files may be inserted as pictures.
SVG has a bright future as a portable and scalable graphic format.
EPS files may be used with PowerPoint if the result will be
rendered on a PostScript film imager.
How can I enlarge or reduce my results?
Use the -scale command line option.
How can I make thumbnails?
Just use a small scale factor, such as -scale 0.3.
Very small text is rendered as lines automatically.
How can I crop my results?
Use one of the -crop, -croprel or -tightcrop command line options.
-tightcrop is close to what I want but it is cropping too closely on one side.
I've found a couple of ploticus prefab commands that do what I want.. is there any way
to combine them all into one output image?
Yes, as of 2.30 you can combine the result of any number of pl invocations into one
Here's how to do this.
I have a program that generates a stream of
X Y coordinates to create a special display. How can I
display my results via Ploticus?
If you can process your stream so that it becomes a stream of ploticus draw commands, you can use the
to render on any device ploticus supports.
How can I do cross-hatch fill for my bar graph?
Hatch patterns are also available as a
which may be useful in getting more distinguishable bar shades.
Hatch patterns may only be used to fill rectangular areas such as bars.
They can't be used for pie graphs.
Can I render a transparent background?
The special color name transparent is available for use when generating images.
Last time I checked this worked with pseudo-GIF but not PNG output..
I have large web log files.
I would like to plot a frequency distribution of number of hits per date and time,
What's the best way to do this?
Script writers can also
use proc processdata with the count action.
Your data will have to be sorted (or at least grouped) so that
all like datetimes are together. A gallery example where this
is done is
Character sets and international support
I need to render superscripts in my title and Y axis label.
This is now supported in a limited implementation (2.30+)..
How can I render a proper less-than-or-equal-to symbol, Portugese
characters, or other special symbols?
This is now described
What about support for UNICODE, BIG-5, etc.
Through SVG or Freetype2 (which can render unicode fonts),
Ploticus is able to render utf8-encoded unicode titles, labels, etc.
More info and an example
I would like dates to use the German month abbreviations rather
than the English.
Is there any way to get thousands separators so that large numbers are
more readable e.g. 3,024,582?
Is there a way to get European-style display of numbers, eg. comma used as
the decimal point, and period (.) used as the thousands separator?
Why isn't vertical text displayed properly on X11?
Ploticus doesn't store its own fonts or have its own
font system; rather it uses fonts that are native to the various graphics platforms
or drivers. X11 does not support vertical fonts (at least it didn't seem to
when I wrote the X11 code several years ago). PostScript and PNG/GIF do support
If I had one feature request for ploticus it would be
support for setting text at angles other than 0 and 90.
This could be done for postscript rendering easily enough
but would be difficult in X11 and PNG/GIF, since the underlying
libraries do not support angled fonts.
Ploticus EPS files don't seem to work with other utility programs
I'm using. Is something wrong with them?
For script writers
How do I..
..take a substring?
..format a floating point number?
..access a particular cell in the data?
These tasks are all accomplished using functions.
Specifically, $arith(), $substring(), $formatfloat(), and $dataitem().
for descriptions of the available functions, well worth getting familiar with.
How do I capture the results of a system command?
The following would execute the 'date' command and the results would be available
in ploticus variable @todaysdate:
#call $shellrow( todaysdate )
How do I set up a loop?
Why does a double at-sign (@@) need to be used in "select"
attributes and in getdata filters?
The first at-sign is stripped off by the script evaluator.
These attributes require that one at-sign survive that step, hence
two must be supplied.
What are #clone and #saveas and how do they work?
#clone and #saveas are used
when doing several similar plots, such as a set of four
bar graphs that have the same style. #saveas saves
the attribute settings for one proc invocation. #clone
uses a set of attribute settings that was saved earlier.
An example is
See also the
scripts syntax page.
My page title has garbage at the end.
Attributes that are multi-line need to be terminated with a blank
line. Perhaps the blank line was left out.
Ploticus seems to be ignoring an attribute I have set.
If the attribute in question follows a multi-line attribute,
you may have forgotten to terminate the multi-line attribute
with a blank line.
According to the documentation, proc getdata sets a ploticus variable called NRECORDS to the number of
records read. However I am having trouble accessing NRECORDS immediately after proc getdata.
Use #endproc to terminate your proc getdata block.
This is a side-effect of the way that ploticus parses scripts.
#endproc is described in the
introduction to scripts.
I have a graph where I set up a plotting area using proc areadef,
proc yaxis, and two separate invocations of proc xaxis. How do I
clone this entire plotting area several times?
You need to use #saveas within every proc that is involved (with
different instance names), and then use #clone all of the procs.
There is no way to clone a set of procs together in one operation.
How do I render two separate scatter plots on the same plot area?
1) Set up your plotting area; 2) read in your first data set; 3) do your first
scatterplot; 4) read in your second data set; 5) do your second scatterplot.
The first areadef stays in effect until a new areadef is specified,
thus any number of plots may be rendered in the area.
Can I make a Y axis on the right edge of the plot rather than the left?
Yes, see gallery example
Is it possible to overlay two coordinate systems on one plot?
Yes, see gallery example
which overlays Celsius and Fahrenheit.
How can I have grid lines in orange every 0.1 unit, and then grid lines
in black every 1.0 unit?
Invoke #proc axis twice and overlay the two, to get more complex
systems of grids, tics, and stubs. See example
which does this.
How can I make autorange work for stacked bars, clustered bars, or error bars?
datafields attribute to specify the data fields, and set the combomode attribute.
Combomode tells it whether to sum the fields or take an overall max.
The prefab scripts stack.pl, lines.pl, and vbars.pl are examples.
An axis labelling question: my xrange goes from 0.5 to 12. When I
do stubs of "increment 1" they are drawn at 0.5, 1.5, 2.5, etc.. I want them to be
at 1.0, 2.0, etc.
Stub placement begins by default at the minima. To override this, the stubrange
attribute can be used. For your case, it would be: stubrange: 1.0
Is there a way to do a broken Y axis?
Yes, although broken axes cannot be done in an automated way.
See gallery example
and the man page for
I am trying to do a plot where the X axis is dates expressed in quarter years
(quarters), to show quarterly results. It is not coming out right.
It is a little bit tricky because data in quarter notation is converted
to a full date midpoint, so the X range needs to be expressed in a full date notation,
then you change units to quarter notation. See the example
Is there any way to make an axis progress from a large value to a small value?
Yes, although it is not entirely straighforward.
See gallery example
I need to automatically find the maxima of a field, and place an annotation there.
Script writers can do this using
action: stats (versions 2.30+) to set some ploticus variables,
which can then drive proc annotate location.
I need to do a scatterplot where the X component is taken from certain data records,
and the Y component is taken from certain other records.
I have one data set with about 80 different cases represented in it. Each case has
several dozen rows of data. I want to produce a separate plot for each case.
What's the best way to do this?
It works within a loop, and causes the data set to be scanned only once.
It requires that the data be sorted by case.
In scripts, when working with
proc getdata filters
it is good practice to set showresults: yes so that you can see what you're doing during debugging.
I have a data set with dates in field 2 and times in field 3.
How can I plot these using the datetime scaling type?
Ploticus datetime values have the form date.time.
The date and the time may in any of the supported notations.
The dot (.) separator is required.
You can use proc getdata's filter attribute to concatentate fields
2 and 3 like this:
filter: ##print @@1 @@2.@@3 @@4 @@5
In the results from sar -u, I can get "idle" time in %. Subtracting that
from 100 would give me the total CPU load data. Is there an easy way to
accomplish that within the ploticus script?
Yes, similarly to the above example, you can use proc getdata's filter attribute.
Suppose your idle time is in field #4:
filter: ##set CPUTOT = $arith(100-@@4)
##print @@1 @@2 @@3 @@CPUTOT @@5 @@6
data display engine
Copyright Steve Grubb