Some basic introductory questions are now addressed on the ploticus home page.

Is there an interactive mode?

No, the main thrust has been to develop an engine that can produce graphics non-interactively, so that it can be run in an automated, unattended way.

What is ploticus good for?

Ploticus is good at making the types of 2-D graphs that you would see in journals for medical and social sciences, newspapers and news magazines, business publications, and so on. Ploticus is good for automated or just-in-time graph generation, handles date and time data nicely, and has basic statistical capabilities. It allows significant user control over colors, styles, options and details.

What is ploticus not good for?

Ploticus is not a function plotting package; it has scant support for mathematical formulas, scientific notations, or inline font or point size changes. You can't plot binary data with ploticus. There are no 3-D types of plots such as contours. Ploticus is not a "marketing" graphics package, and "chartjunk" effects, clip-art, gradient backgrounds, and so on have been intentionally avoided.

I see there are two possible approaches: prefabs vs. scripts. Compare and contrast? If I start out using prefabs will it be difficult to transition to scripts?

For both approaches you use the pl command (or C programmers can use the libploticus API). For prefabs you use pl -prefab prefabname ... and for scripts you use pl scriptfile ... Prefabs are easier because all parameters are given on the command line.. everything else uses reasonable (?) defaults. The new -drawdump functionality makes prefabs more powerful by allowing you to combine/overlay multiple pl runs into one graphic result. Scripts are a lot more flexible but there's a bigger learning curve. A recommended approach is to begin by prototyping with prefabs, then use the -echo stdout option to dump out an equivalent script, then work from there. This helps with transitioning from one to the other. Prefabs are really just special, generalized scripts that can accept a lot of parameters.. but because of this the prefab scripts should not really be the place where you learn how to write scripts.

Is a "config file" the same thing as a "script file"?

No! They are two different things! If you think they're the same thing you will be confused everywhere in the documentation! Here's the difference: You create a script file to tell ploticus how to draw a particular graph (axes, title, reading the data, plotting). On the other hand, you can create a config file (if you want to) in order to get certain "environmental" settings in effect every time you run pl, such as a default date format, international number notation or month names, and so on. You can also the config file option directive to automatically set any pl command line option every time you run pl.

What statistical capabilities does ploticus include?

Some. There are capabilities for curve fitting, computing linear regression, and Pearson correlation coefficient r. There is a built-in facility (proc tabulate) for computing frequency distributions. Means, medians, quartiles, standard deviations, etc. may be computed using proc processdata or proc rangebar.

It would be nice if I could have ploticus process/manipulate my data so I don't have to invoke another program to do this.

Script writers can do a number of manipulations using proc processdata. These capabilities are worth becoming familiar with. Script writers can alter the format of the data on a row by row basis by using proc getdata's filter attribute. If you just need to select certain rows from a data set, you can do this using select attribute when data are read, or when rendering a certain plot.

Can I use ploticus as part of a commercial package or service?

This is possible. Please see the copyright page

Can ploticus get data directly from MySQL, Oracle, Excel, Access, etc.?

Ploticus is not tightly integrated with these other environments. You would need to dump data out into an ascii file first, or pipe the data and tell ploticus to read from standard input. Script writers can also invoke a shell command which generates data, such as this:

	#proc getdata
	  delim: tab
	  command: mysql ...

What about large data sets?

The default capacities are fairly large, and you can increase most of them using command line capacity-setting arguments. Another thing to consider (in scripts) is using proc getdata's select or filter attributes to pare down the size as the data are being read.

Can I import ploticus graphs into PowerPoint, Word, etc.?

Yes. PNG and GIF files may be inserted as pictures. SVG has a bright future as a portable and scalable graphic format. EPS files may be used with PowerPoint if the result will be rendered on a PostScript film imager.

How can I enlarge or reduce my results?

Use the -scale command line option.

How can I make thumbnails?

Just use a small scale factor, such as -scale 0.3. Very small text is rendered as lines automatically.

How can I crop my results?

Use one of the -crop, -croprel or -tightcrop command line options.

-tightcrop is close to what I want but it is cropping too closely on one side.

Try -croprel.

I've found a couple of ploticus prefab commands that do what I want.. is there any way to combine them all into one output image?

Yes, as of 2.30 you can combine the result of any number of pl invocations into one output result. Here's how to do this.

I have a program that generates a stream of X Y coordinates to create a special display. How can I display my results via Ploticus?

If you can process your stream so that it becomes a stream of ploticus draw commands, you can use the draw prefab to render on any device ploticus supports.

How can I do cross-hatch fill for my bar graph?

Hatch patterns are also available as a color option which may be useful in getting more distinguishable bar shades. Hatch patterns may only be used to fill rectangular areas such as bars. They can't be used for pie graphs.

Can I render a transparent background?

The special color name transparent is available for use when generating images. Last time I checked this worked with pseudo-GIF but not PNG output..

I have large web log files. I would like to plot a frequency distribution of number of hits per date and time, What's the best way to do this?

Try the chron prefab with tabulate=yes. Script writers can also use proc processdata with the count action. Your data will have to be sorted (or at least grouped) so that all like datetimes are together. A gallery example where this is done is hitcount

Character sets and international support

I need to render superscripts in my title and Y axis label.

This is now supported in a limited implementation (2.30+).. more info

How can I render a proper less-than-or-equal-to symbol, Portugese characters, or other special symbols?

This is now described here

What about support for UNICODE, BIG-5, etc.

Through SVG or Freetype2 (which can render unicode fonts), Ploticus is able to render utf8-encoded unicode titles, labels, etc. More info and an example

I would like dates to use the German month abbreviations rather than the English.

This is possible. See proc settings or config files.

Is there any way to get thousands separators so that large numbers are more readable e.g. 3,024,582?

Yes, see proc settings or config files.

Is there a way to get European-style display of numbers, eg. comma used as the decimal point, and period (.) used as the thousands separator?

Yes, see proc settings or config files.

Why isn't vertical text displayed properly on X11?

Ploticus doesn't store its own fonts or have its own font system; rather it uses fonts that are native to the various graphics platforms or drivers. X11 does not support vertical fonts (at least it didn't seem to when I wrote the X11 code several years ago). PostScript and PNG/GIF do support vertical fonts.

If I had one feature request for ploticus it would be support for setting text at angles other than 0 and 90.

This could be done for postscript rendering easily enough but would be difficult in X11 and PNG/GIF, since the underlying libraries do not support angled fonts.

Ploticus EPS files don't seem to work with other utility programs I'm using. Is something wrong with them?

Ploticus EPS files conform to the spec as far as I know. One thing to try would be to turn off the latin1 encoding (see proc settings' ps_latin1_encoding attribute)

For script writers

How do I..
    ..perform arithmetic?
    ..take a substring?
    ..format a floating point number?
    ..access a particular cell in the data?

These tasks are all accomplished using functions. Specifically, $arith(), $substring(), $formatfloat(), and $dataitem(). See the functions documentation for descriptions of the available functions, well worth getting familiar with.

How do I capture the results of a system command?

The following would execute the 'date' command and the results would be available in ploticus variable @todaysdate:

  #shell #processrows 
    date
  #endshell
  #call $shellrow( todaysdate )

How do I set up a loop?

Loops may be made to iterate over members of a commalist. See gallery examples colorgrid and lineplot20

Why does a double at-sign (@@) need to be used in "select" attributes and in getdata filters?

The first at-sign is stripped off by the script evaluator. These attributes require that one at-sign survive that step, hence two must be supplied.

What are #clone and #saveas and how do they work?

#clone and #saveas are used when doing several similar plots, such as a set of four bar graphs that have the same style. #saveas saves the attribute settings for one proc invocation. #clone uses a set of attribute settings that was saved earlier. An example is volunteers. See also the scripts syntax page.

My page title has garbage at the end.

Attributes that are multi-line need to be terminated with a blank line. Perhaps the blank line was left out.

Ploticus seems to be ignoring an attribute I have set.

If the attribute in question follows a multi-line attribute, you may have forgotten to terminate the multi-line attribute with a blank line.

According to the documentation, proc getdata sets a ploticus variable called NRECORDS to the number of records read. However I am having trouble accessing NRECORDS immediately after proc getdata.

Use #endproc to terminate your proc getdata block. This is a side-effect of the way that ploticus parses scripts. #endproc is described in the introduction to scripts.

I have a graph where I set up a plotting area using proc areadef, proc yaxis, and two separate invocations of proc xaxis. How do I clone this entire plotting area several times?

You need to use #saveas within every proc that is involved (with different instance names), and then use #clone all of the procs. There is no way to clone a set of procs together in one operation.

How do I render two separate scatter plots on the same plot area?

1) Set up your plotting area; 2) read in your first data set; 3) do your first scatterplot; 4) read in your second data set; 5) do your second scatterplot. The first areadef stays in effect until a new areadef is specified, thus any number of plots may be rendered in the area.

Can I make a Y axis on the right edge of the plot rather than the left?

Yes, see gallery example sa12

Is it possible to overlay two coordinate systems on one plot?

Yes, see gallery example sa13 which overlays Celsius and Fahrenheit.

How can I have grid lines in orange every 0.1 unit, and then grid lines in black every 1.0 unit?

Invoke #proc axis twice and overlay the two, to get more complex systems of grids, tics, and stubs. See example sa14 which does this.

How can I make autorange work for stacked bars, clustered bars, or error bars?

Use the autorange datafields attribute to specify the data fields, and set the combomode attribute. Combomode tells it whether to sum the fields or take an overall max. The prefab scripts stack.pl, lines.pl, and vbars.pl are examples.

An axis labelling question: my xrange goes from 0.5 to 12. When I do stubs of "increment 1" they are drawn at 0.5, 1.5, 2.5, etc.. I want them to be at 1.0, 2.0, etc.

Stub placement begins by default at the minima. To override this, the stubrange attribute can be used. For your case, it would be: stubrange: 1.0

Is there a way to do a broken Y axis?

Yes, although broken axes cannot be done in an automated way. See gallery example brokenaxis and the man page for proc breakaxis

I am trying to do a plot where the X axis is dates expressed in quarter years (quarters), to show quarterly results. It is not coming out right.

It is a little bit tricky because data in quarter notation is converted to a full date midpoint, so the X range needs to be expressed in a full date notation, then you change units to quarter notation. See the example quarters which illustrates.

Is there any way to make an axis progress from a large value to a small value?

Yes, although it is not entirely straighforward. See gallery example hbars4

I need to automatically find the maxima of a field, and place an annotation there.

Script writers can do this using proc processdata's action: stats (versions 2.30+) to set some ploticus variables, which can then drive proc annotate location.

I need to do a scatterplot where the X component is taken from certain data records, and the Y component is taken from certain other records.

Script writers can handle this using proc processdata's action: join (versions 2.30+).

I have one data set with about 80 different cases represented in it. Each case has several dozen rows of data. I want to produce a separate plot for each case. What's the best way to do this?

Use the proc processdata breaks attribute. It works within a loop, and causes the data set to be scanned only once. It requires that the data be sorted by case.

FILTER SOLUTIONS

I have a data set with dates in field 2 and times in field 3. How can I plot these using the datetime scaling type?

Ploticus datetime values have the form date.time. The date and the time may in any of the supported notations. The dot (.) separator is required. You can use proc getdata's filter attribute to concatentate fields 2 and 3 like this:

	#proc getdata
	file: mydata
	filter: ##print @@1 @@2.@@3 @@4 @@5

In the results from sar -u, I can get "idle" time in %. Subtracting that from 100 would give me the total CPU load data. Is there an easy way to accomplish that within the ploticus script?

Yes, similarly to the above example, you can use proc getdata's filter attribute. Suppose your idle time is in field #4:

	#proc getdata
	file: myfile
	filter: ##set CPUTOT = $arith(100-@@4)
        	##print @@1 @@2 @@3 @@CPUTOT @@5 @@6