QDP, the Quick and Dandy Plotter, and PCO files

As mentioned above, PLT is a Fortran subroutine called by programs like xspec and fplot which pass it arrays to plot. Another program that uses PLT is QDP, the Quick and Dandy Plotter. QDP is a handy program that drives PLT to plot ASCII files. As such, QDP can be thought of as the ASCII analogue of fplot which only plots FITS files.

• Getting started: QDP is part of the Xanadu package and is invoked by the command qdp.
• Input files: QDP takes as input ASCII files containing the data to be plotted in columns, like this short example:The default filename extension is .qdp.

  To tell PLT which columns are errors and which are data, the header commands read serr and read terr are used: serr for single-sided errors (one column of errors); terr for twin-sided errors (two columns of errors). Note that xronos, xspec and fplot take care of this automatically: you only need to insert these header commands into QDP files you create yourself.

  Thus for the sample QDP file above, the following header commands can all be used and will have different effects:

  • read serr 1 2 3

    Will create a three-vector plot, with the third and fifth columns being plotted against the first column. The errors for the first, third and fifth columns being the second, fourth and sixth columns, respectively.

  • read serr 2
    read terr 3

    Will create a three-vector plot, with the second and fourth columns being plotted against the first column. This time, the first column has no error bars; the second column has errors in the third column; while the fourth column has errors in the fifth and sixth columns.

  • Omitting any header command will create a six-vector plot with columns 2-6 being plotted against the first, with none having errors.
• Linear x-axes: If you want to create a plot with a regularly spaced x-axis, you don't need to include a whole column of x values: the header command x l (short for 'xaxis linear') can be used instead. For example, if you have 20 values of X-ray flux that you'd like to plot, with their errors, against orbital phase, you can create a QDP file by simply prefacing the data with the header-commands:where, in this example, the phase of the first bin is -0.3107, and the step size of 0.05, i.e. 1/20, is chosen because the data were taken at regular phase intervals spanning one complete orbit.
• PCO (plot command) files: Any of the commands that control the appearance of a plot can be put into a plot command (PCO) file. This option saves time when you have a series of plots that you'd like to look the same. Here's a sample of a PCO file called burst.pco:PCO files, which have the default filename extension .pco, are invoked in PLT with an @ sign:The same command can also be placed in a QDP file.

  Note that the programs like xspec and xronos that call PLT use their own internal PCO files. For example, when you plot a spectrum in xspec, PLT is called with a PCO file that labels the x-axis with 'Energy (keV)'.

More PLT Commands

• Changing character fonts: PLT has four fonts: Normal (the default), Roman (a serifed font like Times), Italic (a sloping version of Roman) and Script (a cursive font). To change the overall font, i.e. for all the characters, use the font command, for example:If you want a few characters to be in a different font, then use the f flag followed by the first letter of the font name. For example, suppose all your characters are in Roman font, but you'd like the name of the spacecraft, as it appears on the filename label, to be in Italic. The corresponding commands would be:
• Greek letters: The Greek font associates a Roman letter (or letters) with a Greek letter. It is case-sensitive and is activated with the g flag. In the following example, the first command includes a capital gamma in the y3 label, while the second includes a lower-case rho in the y4 label:Note the use of the fn flag to reset the font (to Normal) for the rest of the label.
• Subscripts and superscripts: You can include subscripts and superscripts in your labels with the 'down' and 'up' flags d and u, respectively. Note they work relatively, e.g. using a down flag after an up flag will cause the text to appear at the usual level rather than as a subscript. An example makes this clearer:roughly corresponds to the TeX:
• Putting labels anywhere inside the window: Labels can be put anywhere inside the plotting window - not just outside it in the 'standard' positions. Here's an example:The label command is followed first by a position number, in this case 1, which serves to identify it as a 'position' label (as opposed to one of the standard labels) and to distinguish it from other position labels. The next part of the string, 'p 6.4 12', contains the location of the center of the label: the first number is the x-coordinate in the same units as the x-axis and the second number is the y-coordinate in the same units as the y-axis. Finally, comes the label itself enclosed in double quotation marks.

  There are other options: for help, type 'help la #' at the PLT> prompt.

• Grid lines: The command gr on will expand the major tick marks on the x and y-axes into a grid covering the window. The issue of tick marks is fairly involved: for more information, type 'help gr' at the PLT> prompt.
• Writing out a QDP file: The command wd - short for 'write data' - will create a QDP file corresponding to the data you're plotting. Obviously, there's little point if your data started off in a QDP file, but it can be useful tool in programs like xspec which process input files considerably before actually plotting them. The motivation of using the wd command could be to get a file for input into your own plotting program, or, say, to obtain in a simple, direct way, an array containing the effective area of a detector (via xspec's 'iplot efficiency' command).
• Changing background and frame colors: If you're using a color graphics device such as /xw, you can change the color of background with the command scr (set color representation). The first argument is an index to identify the element of the plot:The next three arguments are the normalized intensities (to unity) of the red, green and blue cathode ray tubes. For example, to change the background color to a deep purple:
• Spawning out of PLT: To get a shell prompt without leaving PLT, type $. For example, the two commands:will first create a PostScript file, then send it to the printer. If you want to execute more than one shell command, type $ without anything after it.
• Even more PLT commands: To see all the PLT commands:This will provide an entrance point for more information.

Fitting in PLT

PLT in Xspec: Some Idiosyncrasies

PLT in Fplot: Some Idiosyncrasies

1. fplot offset=yes: You should explicitly set the hidden parameter offset to be 'yes' if you want the first x-value to be subtracted from all the x-values to produce an x-axis starting at zero (the default is 'no'). This subtraction will occur before PLT is called.
2. data3_hard.lc: Self-explanatory.
3. TIME: The column in the FITS file to be used as the x-axis. As we saw in the section on QDP, PLT needs to know whether the second column it encounters is either the x-error array (if there is one) or the first y-array. This is done by enclosing in brackets the name of the column containing the x-error array. Note that fplot is case-sensitive, so you might want to check the column names beforehand with the flcol ftool.
4. RATE[ERROR]: In this example, the y-array RATE does have an associated error array, called ERROR.
5. Lists of rows[-]: This allows part of the file to be plotted, if desired. The removal of array elements occurs before PLT is called.
6. Device: /XWindow, /XTerm, /TK, /PS, etc[?] /xw: Self-explanatory.
7. Any legal PLT command[]: An option for passing a command to PLT before the plot appears. Note that because of the way fplot is written, using this option overwrites fplot's internal PCO file which takes labels for the axes from header information in the file itself.

This page is maintained by the RXTE GOF and was last modified on Thursday, 16-Sep-1999 08:38:14 EDT.