ploticus: prefabs

## Prefabs | Welcome Gallery Handbook |
| Manual page for Prefabs(PL)

## Available prefabs

chron - chronological data (dates, times, etc); tabulate by week, month, etc. | dist - frequency distribution histogram on a data field | lines - line plots with optional data points and error bars, up to 4 groups | pie - pie graphs
| stack - stacked bar graphs, up to 4 levels | scat - scatterplots | vbars - bar graph of 1 or 2 groups with error bars | vbars - with error bars only

Also available:

- draw for interpreting ploticus draw commands
- multidist user-contributed prefab that does multiple, overlaid frequency distributions.``

## What are prefabs?

Prefabs are the easiest way to get started with ploticus.`` You can quickly generate common types of plots without needing to code a ploticus script.`` Just supply several key parameters on the command line or in the data file.`` Everything else uses defaults.``

The `-prefab` command line option tells pl to use a prefab.`` Any of the other command options may also be used along with `-prefab`.`` For example, to use the scat scatterplot prefab you might use a command such as this:

  `pl -prefab scat -png data=results.dat x=2 y=4 -scale 0.7`

## What do I need to do before I begin?

Prefabs work by invoking special ploticus scripts that have been generalized to accept various parameters. These scripts are included with ploticus in the `./prefabs` directory.`` You can use this directory or set up one of your own.`` So that ploticus can find these files, you must supply the full path name of the directory in an environment variable called PLOTICUS_PREFABS (alternatively this may be hard-coded at build time, settable in the Makefile as PREFABS_DIR).``

## Which parts of the ploticus documentation do I need to look at?

Prefab users should find most of what they need to know from this page along with the first three sections of the ploticus handbook.`` Prefabs are a higher-level interface to the functionality available in scripts, so there may be an occational need to jump into the other documentation for certain particulars.``

## Will I outgrow prefabs?

Prefabs are intended to cover common, straightforward situations.`` By their very nature, prefabs do not offer the flexibility that's available with scripts. If you work with prefabs for a while you will probably encounter something that you can't do with prefabs, but could do with a script. At this point I recommend making the jump to script coding; it's not really that hard if you learn by looking at the examples.``

## Passing parameters to a prefab

Parameters may be supplied on the pl command line as var=value pairs as seen in the above example. There is a set of standard parameters that are recognized by all the prefabs unless otherwise noted; it is useful to become familiar with these.`` Individual prefabs also have parameters of their own.``

If convenient, most parameters may be embedded in an input data file, using the #set construct:

       #set x = 2
       #set y = 3
       #set title = Correlation of WBC vs. T-Chol

Some parameters cannot be set from within the data file because they control data scanning. These are `data`, `delim`, `header`, and `comment`.`` There may be others as noted for individual prefabs.``

## Output file names

The -o option may be used to specify output file name explicitly.`` If -o is not given, output file naming is similar to that of pl in other contexts.`` For the above example the output file would be named `scat.png` .``

## Plot data

Plot data must be located in a file.`` The name of the data file is given in the data= parameter the data field delimitation method may be given in the delim= parameter . See dataformat for more information on acceptable data formats.`` Missing data fields are generally skipped, but this depends on what kind of plot is being generated. See dataformat for more discussion of missing data.``

## Customization

Prefabs allow quick looks at data, but there are often details that would be nice to control but can't be adjusted because there is no command line parameter to do so.`` One way to proceed is to copy a prefab script to your own directory and then modify your copy as needed.`` Another option is to make a new prefab variant in the prefabs directory.``

If you just want different defaults for a prefab, you can create a shell script that invokes the prefab as you want it. Then, put a `$*` at the end of the pl command to pick up any overrides that the shell script user enters on the command line (if a parameter is given twice, the rightmost is taken).``

## Examples

All prefab examples are included in the ploticus test suite that is included with all distributions (2.02 and later).``

## Hints

You can create a ploticus config file and use it to set prefab parameters that you always want to be in effect.`` For example:

       option:  comment=#
       option:  delim=comma

It is possible to set parameters from within your data file using embedded #set statements.``

The following pl command line options may be very useful with prefabs: -scale, -color, -backcolor, -tightcrop, -map, -debug, and perhaps -font.``

Be careful not to confuse prefab parameters with pl command line options . Prefab parameters are given this way: `paramname=value`.`` Command line options are given this way: `-option` or `-option value`.``

Most shells allow a backslash (\) for breaking up long commands into two or more lines.``

You can get a multi line title by splitting it over two lines, eg:

        pl -prefab pie1 data=data1 fld=3 label=1 title="Travel expenditures
        By department
        Fiscal year 2000"

HTML clickmaps may be generated using the prefab clickmapurl standard parameter .``

## User-contributed prefabs

User-contributed prefabs are welcome and may be sent to `scg@jax.org`; please include the prefab script file and a man page giving at least one working example.``
data display engine
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` December 10, 2002.