Loving ISIS - Confessions of a Former XSPEC User

Plots
The ISIS plot functions discussed here have supported for many years now any combination of energy (ranging from eV->TeV), wavelength (ranging from A->m), or frequency (ranging from Hz->GHz) X-units with photons, ergs, watts, or mJy based Y-units. (XSPEC just recently added support for a few additional plot units in their plots, such as Jansky vs. Angstrom.) Thanks to the programmability of ISIS, however, we now support arbitrary combinations of units by using just a few simple function calls. The plot on the left presents BTU/Acre/sec vs. (Slug*Sverdrup*Hz)/Terra-Smoot. The code to create this was simple, as we show below:

     add_plot_unit("sshps","btupas"; is_energy=1,
                                     xscale=5.353038e10,
                                     yscale=3274.3436   );
     fancy_plot_unit("sshps","btupas");
     plot_unfold({2,3};power=3,dsym={4,6},dcol={17,4},
                       xlabel="\\fs Energy (Slug\\.Sv\\.Hz/TSmoot)",
                       ylabel="\\fs Flux (BTU/Acre/s)");

Plotting:

ISIS plotting, like XSPEC plotting, is ultimately based upon PGPLOT.

ISIS provides a number of intrinsic plotting functions derived from the PGPLOT library. A partial list of some of the most basic plotting commands are:

     xlabel("string"); ylabel("string");        % X/Y Plot Labels
     id = open_plot("device"); close_plot(id);  % Open and close PGPLOT devices
     xrange(#,#); yrange(#,#);                  % Set plot X/Y ranges
     charsize(#); point_size(#);                % Character/symbol sizes
     plot(x,y);                                 % Line/scatter plots
     oplot(x,y);                                % Line/scatter overplots
     hplot(xlo,xhi,y);                          % Histogram plots
     ohplot(xlo,xhi,y);                         % Histogram overplots
     plot_unit("unit");                         % Toggle between A, keV, etc.
     plot_data_counts(id);                      % Plot counts/bin
     rplot_counts(id);                          % Plot counts, model, and residuals

These will get you a decent amount of functionality. One advantage that they do have over their XSPEC counterparts is that there is no difference between default plotting and interactive plotting. I.e., you do not have to 'drop down' into an IPLOT mode, perform your interactive plotting commands, then 'pop back up' into data analysis mode. It's all one and the same in ISIS. (You're always in analysis mode, and you're always interactive, unless, of course, you are running a script.)

My desire, however, for better plotting in ISIS led me to put a number of wrappers around ISIS plotting commands. (This, in fact, represents the bulk of my .isisrc files.) Among the plotting functions that I have written are:

fancy_plot_unit();

Toggle among eV->TeV, A->m, and Hz->GHz, ergs, Watts, mJy

add_plot_unit();

Define new unit choices not covered in the above

pg_color();

Make a nice green, brown, pink, and dark gold for plots

open_print();

Open a plot device, invoking pg_color first

close_print();

Close the plot device, and optionally invoke gv, xv, etc. to view it

plotxy();

Simple X/Y plots with error bars on either or both variables

plot_counts();

Plot background subtracted data as counts/bin

plot_data();

Plot background subtracted data as counts/sec/fancy_plot_unit

plot_fit_model();

Plot of just the background subtracted model

plot_residuals();

Plot just the data residuals

plot_unfold();

Plot the unfolded spectra

As regards the last plot command - plotting unfolded spectra - I direct readers to my conference proceedings rant against the nature of evil. I won't fully repeat that here, but will only have this to say about the use of XSPEC unfolded spectra: Don't! Ever! There's absolutely no denying that XSPEC has been of enormous benefit to the X-ray community for the past 15 or 20 years, and has enabled a great deal of progress. The one place where it has arguably done more harm than good is in its version of 'unfolded spectra' - the single most abused and misleading XSPEC plotting function. The ISIS version above does not repeat those sins. It still, however, should be used with some amount of caution (try it on a PCA spectrum dominated by a diskbb model, and you'll see what I mean...).

All of my plotting functions can be run in several ways. All will take lists of dataset indices, with plot preferences omitted (sensible defaults will be used). A S-lang list is any set of data in curly brackets: {}. The nice thing about lists is that they are heterogeneous containers- you can fill them with mixtures of integers, floats, strings, arrays, etc. We'll see in a moment how this can be used.

plot_data(1);

% Plot dataset 1 as counts/sec/X-unit

plot_data({1,2});

% Plot dataset 1 & 2 as counts/sec/X-unit

plot_data({1,[2,3]});

% Plot dataset 1, and the combination of datasets 2&3

Any datasets passed in an array, [], will be combined (so long as they have a common energy/wavelength grid- if not, an error will occur).

If choosing plot preferences (e.g., data symbol, residual type, etc.), they can be input either via a structure variable, or as qualifiers. The analysis script shows examples of both. All values/choices refer to PGPLOT color and symbol choices, e.g., 4 is blue when a color or a circle when a symbol.

Additionally, the plotting routines can do all sorts of other crazy things: blue- or red-shift the plotted data, replace the X-axis with a velocity or redshift axis referenced to a specified wavelength or energy, plot the data with or without the background included, etc.

Here are a few examples of plots that you won't normally see coming out of XSPEC. Immediately below on the left is the broken power law/reflection model/diskline fit (yes, unfolded spectra, sorry) showing the radio/PCA/HEXTE data vs. frequency, while the right is the same model showing the RXTE detector space data vs. Angstroms. Again, the same commands to create them interactively were the same commands used to create the hardcopies (via the ISIS intrinsic commands: id = open_plot(); ... plotting instructions ... close_plot(id);). Below those are the data plotted in counts/sec/keV, but vs. velocity and redshift axes, using 6.4 keV as the reference point for zero velocity.

Next up: A Quick Summary.

This page was last updated Aug 5, 2011 by Michael Nowak. To comment on it or the material presented here, send email to mnowak@space.mit.edu.