4 Plotting Packages

4.1 QDP

QDP is an interactive graphics plotting package that began life in the late seventies on a PDP 11/70 at the Goddard Space Flight Center, it doesn’t seem that likely that any of code has survived from that first version.

QDP is now an interactive front end to Tim Pearson’s PGPLOT package, and is distributed by HEASARC as a stand alone segment of their XANADU X-ray analysis package. Most Starlink sites should have XANADU, and hence QDP, already installed. Ask your site manager, or any random X-ray astronomer if you have one to hand, for site specific instructions on how to setup the package for use. The QDP manual is available on the web at http://heasarc.gsfc.nasa.gov/docs/software/ftools/others/qdp/node3.html.

4.1.1 QDP Basic Stuff

QDP takes standard ASCII text files as input, there need to be at least two columns. The first column is taken to X values for the data points, while the second column is taken to be Y values. If there are more than two columns then QDP (by default) assumes that further columns are additional Y values data points (with the same X values). Comments can be included either as separate lines, or at the end of a line of data using the “!” character to signify the start, and the end of a line to signify the end, of a comment. Data values may be separated by spaces, a comma, or tabs. However, each row should contain the same number of columns, although if some data are missing you can enter the word NO instead of an actual number. QDP regards the NO to mean no data available. An example data file is shown below:

By default QDP will look for files with the .qdp extension, if your file has a .qdp extension you do not need to pass this to QDP as it will automatically assume its presence. Although the program is perfectly happy to read files with any extension, it will in fact refuse to read files that do not have a filename extension. This sounds complicated, it is not really, for instance if we create a file called test.qdp, with the above data, you’d plot it by typing:

There are two important features in this short exchange that you should take notice of, firstly, since QDP sits on top of native PGPLOT any device that you can access with PGPLOT you can use with QDP (and is specified in the same way you’d specify native PGPLOT devices, see the PGPLOT Manual. Here we specified that we wished to use X Windows to display our plot so that we can interact with it later. Obviously non-interactive devices like PostScript files are exactly that, you can’t interact with your plot once it is created. Which leads to the second important point, the PLT> prompt, QDP has processed your data file and it is now waiting for commands. The plot from this command is shown in Figure 4.

Figure 4: The default appearance of the test.qdp data file when plotted using QDP.

Since the file contained three columns of numbers, the default mode assumes there are three plot groups. The first plot group determines the X coordinate. The next two columns are plotted as two lines. The name of the QDP file appears in the top left of the plot and your userid, current date, and time appear in the bottom right of the plot. All this can now be changed interactively from the PLT prompt. A useful command at this point is help which provides access to the online help for all QDP commands.

Plots can be rescaled using the rescale command and the axes labelled using the label command, which also controls other labelling like the filename at the top left of the plot. The default is to draw the plots using a line, this can be turned off using line off which will result in each data point being plotted as a dot. This is not that desirable, and the data point marker can be changed using the mark command. A list of markers, and associated numbers can be found by typing mark ? (this will overwrite the current plot on the graphics display, it can be gotten back simply by typing plot). More information on all these commands, and all the others, can be found in the online help from the application which is excellent.

It should be noted that it is important to type plot after making changes to a plot, otherwise the current display will not be changed, and that most QDP commands can be abbreviated (for instance typing ma ? and mark ? will produce the same result).

4.1.2 Plot devices and PostScript output

QDP generates hard copy in the same way it writes to any other device, therefore you question shouldn’t be “How do I get hardcopy of my plot?”, but instead “How do I change the plot device I’m currently using?”. The answer is to issue a dev command to change your current plotting device, for instance:

would change our current plotting device to a landscape PostScript file and re-plot our current plot. The final dev command to (yet again) change out current plot device is important since this closes the PostScript file, without which the file would be empty. By default QDP writes PostScript output to a file called pgplot.ps.

Despite the fact that PostScript output is “just another device” there is a specific command to deal with this common case of device switching, the hard command. You can find out your default hard copy device by:

which tells us we’re currently going to generate a PostScript file as our default hardcopy output. Typing hard on its own will result in the current plot being written to the default pgplot.ps output file. It is possible to override the default hardcopy device, for instance the hard /vps command would generate a vertical (portrait) mode PostScript file no matter what the current default hardcopy output device. It should be noted that the default hardcopy device can be set using the PLT_HARDCOPY environment variable.

By default QDP uses the Simple font since this is fastest, for hard copy output you may wish to change this to something more professional looking like the Roman font. Additionally, since most journals photo-reduce the size of supplied figures before printing it may be advisable to increase the size of the characters on the labels, and also to increase the line width (which by default is one pixel). For instance:

would set the current font to Roman, increase the character size by a factor of 1.3 and set the current line width to 7 pixels before generating a hardcopy of the current plot. Our test.qdp data plotted with these options is shown in Figure 5 (compare with the same figure plotted with the default options, shown in Figure 4).

Figure 5: The appearance of the test.qdp data file when plotted in QDP using a Roman font with csize 1.3 and lwidth 7.

4.1.3 Error Bars

How do we go about telling QDP that the one of the columns in a data file is not data, but instead is a list of errors on our data values? This is done from the QDP file, by putting the READ Serr QDP command at top. This tells QDP that the data has symmetric errors. For instance:

would tell QDP that the third and fourth columns of numbers in our data file are the X and Y errors respectively. Confused? Don’t worry, this confuses many of people to being with, let us take a step back. Basically when it thinks about columns QDP doesn’t count columns that contain errors, so that to QDP there is not really four column in our file. Instead there are only two, a column containing X data and the associated errors, and a column containing the Y data and the associated errors. Perhaps this will make more sense if we separate the columns QDP perceives using commas. Hence:

Does it make more sense now? The READ Serr command basically tells QDP that the the two lists of numbers should each have two real columns (one for data, one for errors). You can see what QDP makes of this file in Figure 6.

Figure 6: Our second test data set plotted using QDP with the default options.

You can also tell QDP to use two-sided errors using the READ Terr command. It takes three real columns to specify a two-sided error. The first column is the central value, the second (which must be positive) specifies the upper error the third column (which must be negative or zero) specifies the lower error. For instance the file:

would plot a point at $\left(1\pm 0.1,2{\pm }_{0.2}^{0.1}\right)$

4.1.4 That “Date and Time” Thing

A commonly asked question by QDP novices is how to turn off the display of the date and time in the bottom right hand corner. This is done simply through use of the time command: time off will suppress printing the current date and time, while time on will restore this default behaviour.

4.1.5 Fitting using QDP

QDP has some basic fitting capabilities, for instance to fit our second lot of test data with a model consisting of a constant, linear and quadratic components (in other words fit it to the equation $Y=X^2+X+C$) we must first define a model, e.g. 

Here we have simply accepted the default values (VAL) by hitting return, I could have instead entered likely estimates for our model parameters. This procedure becomes necessary for more complicated data and models. Having established which model we want to fit to the data, now type fit.

You’ll see that we’ve got an acceptable fit, if you look at the display you’ll see that the a line has been drawn showing the fit. The fit doesn’t look very nice on screen however since QDP has illustrated its fit with a line having only the same number of points as our initial data values. If you want a smoother curve for a publication you should now type:

This will replot the fit with 200 points interpolated along the best fit model, which looks much nicer, as can be seen in Figure 7. Note that the fit parameters and variance, along with the number of data points fitted, is shown down the right hand side of the plot.

Figure 7: Our second test data set plotted using QDP with best fit model.

You can get a list of the different possible models available by typing model, e.g. 

While to get help on specific model components you must turn to the online help system, e.g. 

You’ll note that the CONS model has, obviously, only one component while:

has three, GN, GC and GW.

It is possible to save the current model to disk using the wmodel command, e.g. 

will create a file.mod file. To read this model back into QDP use the command model @file. If you do not enter a file name with the wmodel command, then the model is written to the screen.

The uncertain command can now used to estimate uncertainties in the parameter values, e.g. 

would give an error estimate for the first parameter of our fit (CO). You’ll see that this shows us that we really didn’t need to add a constant value to our model, since our value $0.765\pm 2.188$ is consistent with zero. More information on fitting models can be found in the QDP manual and online help.

4.1.6 QDP Files

You’ve already seen that you can instruct QDP to treat the columns in your .qdp file differently using the READ Serr command. QDP also lets you put commands that you would normally type at the PLT prompt into you .qdp file, for instance:

Would plot our second example data file with the X axis labelled “Time” and the Y axis labelled “Distance”. You can in fact have QDP files that are entirely commands, these have the default extension .pco instead of the usual .qdp. For instance if we have a file test.pco which contains:

and at the PLT prompt we typed:

we would execute the commands contained in the test.pco file, putting the label “Time” on the X axis, “Distance” on the Y axis and the string “A Test Plot” along the top of the graph.

4.1.7 COD and QDP models

You can use something called COD (COmponent Definition) to generate new functions that can be used as components in QDP models. COD can also be used interactively as a reverse polish calculator. More information on COD is available in the QDP manual and from COD’s own online help, e.g. 

4.2 PONGO

PONGO is another interactive plotting package that, like QDP, is based on PGPLOT. The PONGO package can used from both the Starlink/ICL and IRAF/CL command languages and integrates with other Starlink software packages.

Using graphics between different applications packages is often difficult because once one package has finished plotting and completed execution all information concerning the contents of the plot is lost. PONGO makes use of the Starlink Applications Graphics Interface (AGI) libraries, see SUN/48, which allows different graphics applications to be used to display images, draw contours and annotate, for example, on the same plot without each application losing access to the plot dimensions. This means, for instance, that you can display an image using the KAPPA display application and then annotate it using PONGO.

Full details of the PONGO package can be found in SUN/137 which should be available from your Starlink site manager.

4.3 SM

Another interactive plotting package that may be found at your site is SM. Full details about SM can be found in the SM User Guide (MUD/159) and the SM Tutorial (MUD/160) which can be obtained from your Starlink site manager.

4.4 GNUplot

GNUplot is a command-driven interactive function plotting program that, for once, doesn’t sit on top of PGPLOT. It can be used to plot both functions (e.g. $sin$) and data points in both 2 and 3D plots (i.e. contour plot, mesh, etc.). Despite its name GNUplot is not written/maintained by the FSF, nor is it released under the GPL.

An important thing to note about GNUplot is that its commands are case sensitive (like UNIX) and should be entered in lower case. Commands may extend over several input lines (for clarity) by ending each line but the last with a backslash (\). The backslash must be the last character on each line. Strings are indicated with quotes, although they may be either single or double quotation marks.

Since GNUplot accepts the name of a command file as a command line argument or as a redirection from standard input, e.g. 

or

the application is therefore very suitable for batch processing of data files. Extensive documentation on GNUplot is available on the web at http://www.cs.dartmouth.edu/gnuplot_info.html, and while the application can be used as at the simplest level as a plotting tool for 2D data, GNUplot has many powerful features including plotting of 3D parametric functions (see Figure 8) and data, and the ability to integrate functions and show the result graphically.

Figure 8: A plot of the function $\left(1-0.1cos\left(v\right)\right)cos\left(u\right),\left(1-0.1cos\left(v\right)\right)sin\left(u\right),0.1\left(sin\left(v\right)+u/1.7-10\right)$, a parametric helix, using GNUplot

4.4.1 Co-ordinate systems

One of GNUplot’s strengths its ability to plot functions, and data, in different co-ordinate systems. For instance Figure 9 shows a plot of the function $cos\left(2x\right)$ in polar co-ordinates.

Figure 9: A plot of the function $cos\left(2x\right)$ in polar co-ordinates using GNUplot.

4.4.2 Plotting 3D data

GNUplot has quite powerful 3D plotting abilities, using the splot command, reading either from an ASCII or binary file. ASCII data files should have the data stored in a format that looks something like:

while binary files should have single precision floats stored as follows:

GNUplot will automatically determine if the data is in binary or ASCII format when it is read in using the load command.

An example of a 3D data file plotted using the splot command is shown in Figure 10. While another, very impressive, example from the GNUplot manual is shown in Figure 11.

Figure 10: A 3D plot using GNUplot.

Figure 11: A 3D plot of a digitised blue whale using GNUplot.