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.

Plotting, Part II:

New as of Oct. 2013: I have added two new plot functions, plot_comps and plot_double. These two functions will plot any additive component that has an independent and unfrozen/untied normalization parameter, one at a time. Specifically, all parameters that ISIS considers to be a "normalization" (usually, but not always, with a .norm suffix) that aren't frozen, aren't limited by min/max values that don't encompass zero, aren't tied to and aren't a function of another parameter, are zeroed out and then are individually set to their original values and are independently plotted. Furthermore, new plot options for this mode (ccol and cstyle) are added to allow the model components to have different colors and line styles (e.g., dashed) from the total model. The plot_double function allows one to place two of the above plot functions into a single plot, e.g., plot_unfold and plot_data, while also plotting individual model components (with alternate colors and line styles) into each of these subplots.

The following two plots were created with the commands:


plot_comps(1,popt,&plot_unfold;res=3,power=3,
                               yrange={1.01e-13,NULL,0.81,1.19});

plot_double(1,popt,&plot_unfold,&plot_data;res=3,power=3,
                    yrange={1.01e-13,NULL,0.0051,NULL,0.81,1.19});

Next up: A Quick Summary.

This page was last updated Oct 21, 2020 by Michael Nowak. To comment on it or the material presented here, send email to mnowak@physics.wustl.edu.

MIT Accessibility