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


Back to ploticus home

Ploticus scripts handbook



data display engine  
Copyright Steve Grubb


Ploticus is hosted at http://ploticus.sourceforge.net   Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads


Markup created by unroff 1.0,    March 11, 2009.