Where can I get ploticus?

ploticus.sourceforge.net or mirror sites. It is free software.

Where can I report problems or get help?

See the troubleshooting and bug reports page and the ploticus news group. If you've given the docs a fair go and still have a question, feel free to ask by emailing scg@jax.org or posting to the ploticus news group.

What computing environments are supported?

Most unix platforms and win32.

How many users are there?

Some users who have written in are present on the current or earlier user feedback pages.

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 graphs that you would see in journals for medical and social sciences, newspapers and news magazines, business publications, and so on. Ploticus is pretty good at handling date, time, and category data. Ploticus has flexibility with regard to styles and colors. Ploticus is well-suited for automated or repetitive tasks.

What is ploticus not good for?

Ploticus is not a function plotting package; it has little support for mathematical formulas or scientific notations. Ploticus is not a "marketing" graphics package; it has little support for 3-D effects, clip-art, gradient backgrounds, and so on.

Are any statistical capabilities included?

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 rangebar.

How does ploticus compare with other freeware plotting/charting packages?

Here is a list of some other plotting packages (thanks to Arthur Ferruzzi).

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

This is possible. Please see the copyright page

GETTING STARTED

What is the easiest way to get started?

Download the software. Try one of the included examples, eg. pl stock.htm. Then, see if one of the available prefabs is close to what you want. When a prefab is used, all that needs to be specified by the user are several key parameters.

For more flexibility and power, you can develop your own ploticus scripts

How do I invoke ploticus?

The pl command.

How do we invoke ploticus automatically? How can we generate on-the-fly graphs for our web site?

You can invoke pl directly as a CGI , and there are other approaches as well.

The chron prefab is close to what I want, except..

Prefabs are intended to cover basic needs, but due to their very nature as a simple interface they aren't nearly as flexible as developing ploticus scripts. If you are running into limitations, consider making the jump to scripts

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

No. A script file is a file that you create to tell ploticus how to draw a particular graph. It contains settings for the size of the plotting area, defines the title, axes and where to get data, and tells what type of plot to draw. A config file is a file that you can create if you want to, that defines certain settings that you want in effect all the time, for every graph you generate. Typical uses of a config file are to set a default date format, or to set international number notation or date notation. You can also set any pl command line option automatically from within a config file. Config files are completely optional, and may be used with prefabs and scripts.

INPUT

What data formats are accepted?

See the data formats documentation

What data types and scaling types are handled?

See the scale units documentation

How does my data need to be organized in order to plot from it?

See the data formats documentation

Can I assign names to data fields?

See the data formats documentation

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. You can also have ploticus invoke a shell command which generates data, such as this:

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

Can ploticus automatically determine the axis based on the range of the data?

Yes. Prefabs will do this automatically. If writing a script use proc areadef autorange. A script example that does this in both X and Y is scatterplot10.

What about large data sets?

The capacities are fairly large. If your data set is too large, and you're writing a script, you may be able to use proc getdata select or filter to pare down the size.

OUTPUT

What graphics file formats can be created?

SVG , PostScript, and EPS are generally supported in all builds. Unix builds support interactive X11 display. GIF, PNG, JPEG, and WBMP are available depending on configuration (see the download page and/or the Makefile). Clickmap support is available for images and SVG.

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 we process and perhaps annotate ploticus graphs for submission to a journal, etc.?

See pre-press work and publication-quality graphs

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.

SCRIPTS 101

I need a customized plot. If I am coding a script from scratch, what is the bare minimum of code I need?

See the introduction to scripts.

How should ploticus script files be named?

See the introduction to scripts.

Do I have to learn the script language?

You do not, if you can get by with just the prefabs. Otherwise, you do. The introduction to scripts provides a place to start. For serious script development, I recommend downloading the entire doc node including gallery examples and handbook. Then you can search and peruse all of the material locally using "grep" or whatever.

How do I perform arithmetic?
How do I take a substring?
How do I format a floating point number?
How do I 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 the wide range of available functions. Becoming familiar with the range of functions available is a big step towards making the most of this tool.

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
   #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 introduction to scripts

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.

CHARACTER SETS AND INTERNATIONAL SUPPORT

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 should be able to render utf8-encoded unicode titles, labels, etc. beginning in version 2.05.

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.

HOW DO I ...

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.

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 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?

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 Proc tabulate can also be used to do frequency distributions, but it has an upper limit of 200 bins.

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: @@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)
         	@@1 @@2 @@3 @@CPUTOT @@5 @@6