8 Creating Complex Plots

 8.1 A simple ICL procedure
 8.2 A simple CL procedure
 8.3 Example procedures

Repeating complex sequences of PONGO commands by hand can become boring and is likely to lead to many mistakes (particularly on those occasions when you want to create a hardcopy and cannot even see the current state). The way to get around these problems is to use the abilities of the ICL or CL command languages to create procedures.

The following two sections show extremely simple examples of how to start doing this in both languages. To get further you’ll need to consult the appropriate documentation, SG/5 in the case of ICL and the “CL Programmer’s Manual” and “An Introductory User’s Guide to IRAF Scripts” for CL.

8.1 A simple ICL procedure

A simple procedure that reproduces the tutorial example looks like:

  proc icltest file
     begplot xw
     readf data=(file) xcol=1 ycol=3 all reset
     dlimits
     boxframe
     points 3
     label ’X axis’ ’Y axis’ ’PLOT TITLE’
     endplot
  endproc

If you enter this text into a file say called icltest.icl and use the following commands from ICL:

  ICL > load icltest
  ICL > icltest (TUTORIAL_DATA)

The data from the tutorial example will be plotted as before. One immediate advantage of this method is that we can now plot data from columns 1 and 3 of any file.

If the contents of the procedure are wrong or need a slight modification then you can edit the procedure from ICL. Try the command:

  ICL > edit icltest

This puts you into an editor and you can modify the procedure. (If you haven’t set an environment variable EDITOR or used the ICL command set editor, you’ll find yourself in vi. To exit from this type the command :q and now use the set editor command.) If you made a modification to the procedure this can be viewed using the command:

  ICL > list icltest

All the currently available procedures are shown using the command:

  ICL > procs

If you do modify a procedure from ICL use the:

  ICL > save icltest

command to write out your changes (you should use the name of your procedure instead of icltest).

8.2 A simple CL procedure

A simple CL procedure that reproduces the tutorial example looks like:

  procedure cltest (datafile)
  string datafile
  begin
     begplot xw
     readf (data=datafile, xcol=1, ycol=3, all=yes, mode=h )
     dlimits
     boxframe
     points 3
     label ("X axis", "Y axis", "PLOT TITLE")
     endplot
  end

If you enter this text into a file say called cltest.cl and use the following commands from CL.

  po> task cltest = cltest.cl
  po> cltest pongoexamples$tutorial.dat

The data from the tutorial example will be plotted as before. One immediate advantange of this method is that we can now plot data from columns 1 and 3 of any file.

Another way in which you can create CL scripts is to use the mkscript command.

8.3 Example procedures

These examples are intended to show some of the features of PONGO and also provide examples of complex procedures for both the ICL and CL command-languages. All these procedures can be found in the directories $PONGO_EXAMPLES and pongoexamples$ respectively. ICL examples have file extensions .icl and CL examples .cl.

The ICL procedures will prompt for a graphics device and should be invoked from the ICL> prompt using the ICL command load, e.g. :

  ICL> load $PONGO_EXAMPLES/ppdotdiag

and their execution can be followed if the ICL command set trace has previously been executed.

The CL procedures are defined as tasks by the pongo command and can be run by just typing their name i.e. :

  po> ppdotdiag

Note that some of the examples involve the colour representation of lines, which may be difficult to see on a greyscale device (e.g. on a monochrome Postscript device). It is recommended that a colour image display device is used to run the example procedures.

8.3.1 Spectrum

This procedure produces Figure 1, a plot of a low resolution IUE spectrum extracted by IUEDR (SUN/37) and written using the IUEDR command OUTSPEC SPECTYPE=2. The output file was subsequently edited to make the file label lines PONGO comments and to add a line of PONGO column labels (see §5) at the beginning of the file. IUEDR indicates bad or missing data in an output spectrum by attributing zero fluxes to the affected wavelength samples. These can be detected and discarded using the SELCOND parameter of the READF command: e.g. 

  PONGO> readf (SWP_DATA) selcond="Flux > 0.0" noall

In this example PONGO draws a polyline across all missing data flagged by IUEDR.


pdfpict

Figure 1: SPECTRUM example.


8.3.2 Errors

The procedure ERRORS was used to plot Figure 2. This example demonstrates plotting simple error bars using PONGO (the ERRORBAR command) and also performing simple statistics on the data (the FITLINE and FITCURVE commands). Note that a summary of the statistics is reported for each fit to the data.


pdfpict

Figure 2: ERRORS example.


8.3.3 Histogram

The procedure HISTOGRAM (histogramtest from CL) was used to plot Figure 3, which illustrates the plotting of histograms with PONGO (the PLOTHIST command). This procedure also illustrates how the drawing of the box around the plot can be controlled using the BOXFRAME command.


pdfpict

Figure 3: HISTOGRAM example.


8.3.4 Ppdotdiag

This procedure produces Figure 4, a period versus period derivative diagram for pulsars. Note the use of a column within the data file to set the symbol number of each plotted point, and the use of the PONGO_NDATA global parameter for making a title containing the number of points that have been read in (in CL this uses the output parameter readf.ndata)


pdfpict

Figure 4: PPDOTDIAG example.


8.3.5 Ellipses

The procedure ELLIPSES (ellipsetest from CL) was used to plot Figure 5, which illustrates the use of the ELLIPSES command for plotting error ellipses.


pdfpict

Figure 5: ELLIPSES example.


8.3.6 Projections

This procedure illustrates some of the different ‘geometries’ available in PONGO. It plots four different views of the distribution of a selection of the known pulsars in Right Ascension and Declination to produce Figure 6.


pdfpict

Figure 6: PROJECTIONS example.


8.3.7 Radec

This procedure shows how the BOXFRAME command can be used to draw labels in HH MM SS.S & DD MM SS.S format. The output from it is shown in Figure 7. The objects are some of the pulsars from Figures 6 and 4.


pdfpict

Figure 7: RADEC example.


8.3.8 Vector

This procedure shows the VECT and PVECT commands being used to plot the proper motion vectors of a set of bright stars. The stars are selected to have proper motions in RA greater than 0.5 arcseconds and the distances shown correspond to 100000 years of travel.


pdfpict

Figure 8: VECTOR example.


8.3.9 Interactive

After executing the examples it is a good idea to gain some experience with the CURSE application. This can be done using the procedure INTERACTIVE. The procedure will plot a graph and then invoke the CURSE application, resulting in the following instructions being printed on the screen:

  CURSE cursor options:
     Q - Quit.
     D - Draw to the cursor position.
     E - Expand the plotting limits.
     G - Calculate the gradient.
     L - Label the plot.
     M - Mark a point.
     O - Left justified annotation.
     P - Right justified annotation.
     S - Shrink the plotting limits.
     V - Move to the cursor position.
     X - Get the cursor position.
     Z - Zoom the plotting limits.

where the letter signifies the key that is to be pressed on the keyboard to achieve the desired effect.

If you have examined the example file for INTERACTIVE you will have seen that a label has been read in for each of the data points. It is now possible for you to use these labels by moving the cursor close to a plotted point and pressing O or P. When you do this, a label for the point nearest the cursor will be written at the cursor position. Do this for several points and then press Q to exit from the CURSE command. PONGO will have remembered the particular labelling that that you have performed and will then use the command WRITEI LABLST=YES to write the PONGO commands required to recreate these labels to a specified file. (You can use the procedure INTERACTIVE to explore the other functions of the CURSE application.)

The ZCOL area has been filled with the distances to each of the pulsars. These values can be used to plot points whose sizes are inversely proportional to distance (i.e. the closer pulsars are larger) by first taking the reciprocal of the ZCOL area with the CCMATH command:

  PONGO> CCMATH Z=1/(Z+0.1)

and then the points plotted with the command:

  PONGO> SIZEPLOT

Note here that a small positive value has been added to the distance data (i.e. Z+0.1) to avoid very large symbols for nearby pulsars.

8.3.10 AGI

This example illustrates the interaction between the KAPPA package (SUN/95) and PONGO via the AGI graphics database. Here, the image display has been done using the KAPPA DISPLAY command and PONGO has been used for all the line drawing (note this example is not available under CL).


pdfpict

Figure 9: AGI example.