## Ploticus Prefabs Handbook

Version 2.32
Prefabs

Manual page for Ploticus_Prefabs_Handbook(PL)

Ploticus prefabs are the easiest way to use the package.`` You specify certain parameters directly on the command line, and everything else is handled automatically.``

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. | 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 generates graphs. The `-prefab` command line option selects a prefab, eg: `-prefab chron`. You'll also need to specify the output format you want, eg. `-png` and the desired output file name eg. `-o try35.png`. Other handy command line options include `-debug` and `-scale`. There are a lot of other command line options, almost all of which can be used with prefabs. Be careful not to confuse pl command line options such as `-scale 0.7` with prefab parameters.. they are two different things.

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. Another possibility is to set this when compiling ploticus (see `PREFABS_DIR` in the Makefile). 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 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

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