Ploticus Prefabs Handbook |

Version 2.41 Mar2009
Prefabs
| |
|
Manual page for Ploticus_Prefabs_Handbook(PL)
Prefabs offer an easy way to try ploticus...
there's no script file to create... command line args control everything.
Prefabs are meant for exploratory work and one-shot looks at data.
Flexibility is limited. For production applications or projects needing any degree of customization,
ploticus scripts
are the recommended way to go, not prefabs.
Also, prefabs tend to be second-tier with regard to ongoing development and support.
The standard prefab parameters are common to most of the
various prefabs and control things like reading in data, setting up axes, legends, and so on.
Available prefabs:

chron - chronological data (dates, times, etc); also can tabulate on week, month, etc.
|

compare - convenient comparison of 1-4 vars across 1-15 categories. Computes means and SD, and displays groups of bars.
Currently suspended / unavailable
|

cumufrac - cumulative fraction plots (linear or log)
|

dist - frequency distribution histogram, numeric or alphanumeric bins
|

heatmap - heatmaps, density grids, and similar displays
|

lines - line plots with optional data points and error bars, up to 4 groups
|
pie - pie graphs
|

scat - scatterplots, with optional regression line, point labeling,
and error bars, up to 4 groups
|

stack - stacked bar graphs up to 4 levels
|

stack - also does stacked area plots
|

vbars - bar graph of 1 or 2 groups with precomputed error bars
|

vbars - also just the precomputed error bars
|

vdist - bee swarm distribution of one variable.
|

vdist - histogram comparison of two variables.
|
|
- draw
for processing drawdumps or ploticus draw commands
- multidist
multiple overlaid frequency distributions
- processdata
use ploticus as a data processing filter (no plots)
|
Gallery of all prefab examples
What's new - prefabs
Summary of the standard prefab parameters
Quick start
1. Download the software and install.
2. Set the PLOTICUS_PREFABS environment variable to the pathname of the ploticus ./prefabs directory.
Be sure that the pl command is in your command search PATH.
3. Look at the prefab examples gallery and find an example close to what you want.
4. Execute the pl command appearing below the example.
5. Check the standard parameters and the individual prefab manual page for
more possibilities.
6. Use prefabs as far as possible for prototyping and "quick-n-dirty" uses.. if you need "extreme"
customization, use the -echo stdout commmand line option to dump out the equivalent
ploticus script, and go from there.
7. Overlay and/or combine multiple pl runs using -drawdump (see below)
The pl(1) command
The pl(1) command
is what you'll generally use to generate graphs.
Use the -prefab command line option to select which prefab you want, eg: pl -prefab chron.
There are also options for specifying which output graphic format you want, and the output file name.
For instance,
pl -prefab chron -png -o mygraph.png ...
There are a number of other command line options that are useful
with prefabs, for scaling, setting overall colors, and much more.
See the pl(1) manual page for more info.
Note: pl command line options begin with a dash, but prefab parameters don't.
The PLOTICUS_PREFABS environment variable
must be set to the directory where prefab files are located. Normally this is a
directory called ./prefabs in the ploticus distribution.
Note that, to avoid compatibility issues, the prefab files should be from the same ploticus version as the pl executable.
Prefab parameters
control what prefabs do.
Parameters are usually specified on the command line using the form parametername=value
but they may also (sometimes) be set
from within an input data file or in your ploticus config file.
There are standard prefab parameters
which are parameters that are in common to most of the prefabs, and specify plot data fields, title, axes,
data format, legends, and so on. There are also parameters that are
specific to individual prefabs ... these are described on the individual prefab manual pages.
Commands and the shell
Ploticus prefab commands can get rather long.. most shells allow backslash for
continuing commands onto additional lines.
If a parameter value contains embedded whitespace the value should be enclosed in quotes.
You can get a multi line title by splitting it over multiple lines. Here's an example:
pl -prefab pie1 data=data1 fld=3 label=1 \
title="Travel expenditures
By department
Fiscal year 2000"
Input data
Input data can come from files or standard input.
It should be plain ascii text. Whitespace, tab, and comma delimited fields are supported.
You can plot various types of data including numeric, category, date, and time.
For date and time data, use the chron prefab.
Overlaying and combining plots from multiple pl runs
Beginning in version 2.30 you can use the -drawdump and -drawdumpa command line options
to overlay and/or combine plots from multiple pl runs into one graphic image / result. Example:
pl -prefab scat "rectangle= 1 1 3 3" .... -drawdump mydump
pl -prefab scat "rectangle= 4 1 6 3" .... -drawdumpa mydump
pl -prefab draw dumpfile=mydump -png -o all.png
Hints:
- if you're setting a background color this should be done only in the first pl invocation.
- for overlays using the same plotting area rectangle and scaling, turn off axis generation (xaxis=none yaxis=none).
- for overlays using same plotting area rectangle and different scaling, use eg. yaxis=left for one and yaxis=right for the other.
- clickmap/mouseover info is not retained in drawdump file, but can be generated by individual pl invocation for PNG (etc.)
- you can get a graphic result while generating a drawdump.. just specify the device argument somewhere to the right of
the -drawdump filename argument on the command line.
Customizing
It is possible to include chunks of ploticus script code to add annotations, etc.
(see the standard parameters include1 and include2).
Otherwise, for needs that aren't addressed by existing prefabs, you can develop a ploticus script.
Get as far as you can with the prefab, then use the
-echo stdout option to dump out an equivalent script.. then modify the script as needed.
Notes
- No error message is issued when an invalid prefab parameter name is used.
Reference
Input data for plotting
Data types and scaling: numeric, category, date, time
Absolute units, scaled units, etc.
Attribute types: dfield, plotvalue, locvalue, printf, string, text, multilinetext
Linedetails
Symboldetails
Textdetails
Select expressions
Colors
Fonts
Dates
Times
Your ploticus config file - settings to be in effect all the time
What's new - general
What's new - prefabs
FAQ
Newsgroup
pl(1) man page
libploticus API
Web usage notes
Imagemap, clickmap & mouseover text bubbles
Dynamic content and just-in-time usage notes
Direct CGI mode
Paper-based report usage notes
Large-sized poster usage notes
Pre-press work usage notes
SVG notes
SWF (shockwave-flash) notes
Download
Build instructions
Troubleshooting & support
Limitations
Copyright and permissions
Steve Grubb's home page
Back to ploticus home
Ploticus scripts handbook
|
 data display engine
Copyright Steve Grubb
|