Ploticus Prefabs Handbook


Version 2.33 Jun'06

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 (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
SourceForge Logo


Markup created by unroff 1.0,    June 02, 2006.