Appendix D: Overview of PLT

XSPEC uses the PLT library, which is in turn based on PGPLOT^D.1, to implement its plotting capabilities.

Extensive documentation for the PLT graphics routine is available in the QDP/PLT Users's Guide and from PLT's interactive help. This appendix is intended to provide information to assist in using PLT from within the XSPEC program.

Within XSPEC, it is possible to set your graphics device using the cpd command. Any PGPLOT device supported by your local version of PGPLOT is accepted. The cpd command can also be used to display a list of all PGPLOT devices. If you fail to enter a device name, you will be prompted for a PGPLOT device every time you generate a new plot.

From XSPEC, there are two ways to call the PLT routine. Both have the same syntax which is described in the corresponding manual section.

The plot <plot mode> command will produce a graph and control will return immediately to XSPEC.

The iplot <plot mode> command will put XSPEC into interactive plot mode. The prompt

PLT>

will appear after XSPEC has finished producing the graph. At this point, you can enter PLT commands to inspect interesting parts of the graph, add labels, or make a hardcopy file for later printing.

Getting started with PLT

In the following description of PLT commands, the full command is described. Capital letters denote the shortest abbreviation of the command that will be recognized. Here is a brief guide to some of the PLT commands that can be entered when iplot is invoked.

• HElp will provide you with descriptions of the PLT commands.
• Plot redraws the display using all of the commands that change the graph entered since the last plot.
• Rescale followed by two numbers, will set the minimum and maximum of the plotted x-range to the numbers specified. Without further arguments, Rescale X or Rescale Y will reset the minimum and maximum values to their default values. Rescale also updates the screen immediately. Other commands allow you to make several changes to the the graph without having to wait for the screen to be updated after every change.
• LAbel <Top,X,Y> [<string>] adds labels to various locations on the graph. For example, typing LA Top EXOSAT was great will cause the message “EXOSAT was great” to appear at the top of the graph the next time the display is redrawn. Without the string argument the current label for Top, X, or Y is set to the empty string.
• Hardcopy [?, PGPLOT plot device] creates a file that can later be printed. Since it redraws the graph and sends it to a file, it does not reproduce what currently is visible on the graphics display, but rather what you would see if you re-issued the Plot command. With the optional “?” argument, Hardcopy returns the current hardcopy plotting device. This can be overridden with Hardcopy [PGPLOT device name].
• WData writes a QDP data file to disk. The wdata output file depends on how complicated the plot is (ie. multiple spectra, models, etc.); for the standard case of "plot data" with 1 spectrum and a fitted model, 5 columns of data are given:
  • col 1: x-axis value (same for both spectrum and model, in either channel energy or wavelength units depending on the plot)
  • col 2: x-axis error. Half of the bin-width, in either channel, energy, or wavelength units
  • col 3: y-axis value for the spectral data point
  • col 4: y-axis error for spectral data point (the +/- length of the error bars)
  • col 5: y-axis value for the model
  Since the models aren't plotted with y-axis errors, there is no col 6 for the model error.
• EXit returns control to XSPEC. Any changes you have made to the plot will be lost.

PLT Command summary

CLear	Immediately clear the graphics device
COlor	Change the default colour index
CONtour	Produce a contour plot
CPD	Change the plotting device
CQuit	Clear the graphics device and return control to XSPEC
CSize	Change the default character size
Error	Control whether errors are displayed and used in fitting
EXit	Exit PLT and return control to XSPEC
Fit	Fit the PLT model to the data
FNy	Evaluate the model at the specified location
FOnt	Change the default text font
Freeze	Freeze a parameter value
GAp	Change the default gap size between the data and the edge
Grid	Control the location of the major and minor tic marks
Hardcopy	Make a file that can later be printed
HElp	Obtain help on any PLT command
Imodel	Numerically integrate the model over specified range
LAbel	Add or remove labels from the plot
LIne	Control whether a line is used to connect data points
LOg	Control whether data is plotted using a log10 scale
LStyle	Change the default style of the line connecting the data points
LWidth	Change the default line width
MArker	Control whether the data points are plotted with markers
MOdel	Define a PLT model
Newpar	Change a parameter value associated with the model
PLot	Immediately re-plot the data
PRompt	Change the PLT$\rangle$ prompt
Rescale	Reset the minimum and maximum plot range
SCr	Change the color representation of the specified color index
SHow	Display the values of PLT internal variables
SKip	Control how PLT divides data into vectors
STatistics	Compute various statistical properties of the data
THaw	Allow a parameter value to vary during a fit
Time	Control whether the time stamp is plotted
Uncertainty	Compute the uncertainty in a parameter value
VErsion	Display date of the most recent modification to PLT
Viewport	Control the size of the viewport plotting area
WData	Write a QDP data file to disk
WEnviron	Write both QDP data and header files to disk
WHead	Write a QDP header file to disk
WModel	Write a model file to disk
Xaxis	Define the method used to calculate the x-variable
Yaxis	Define the y-axis scale for a contour plot
$	Execute operating system commands
@filename	Read commands from a PLT command (.pco) file