Frequently Asked Questions

Help! Help doesn't work.

Why doesn't Xspec report the reduced chi-squared anymore?

How do I calculate the flux from only one component of my model? Can I get an error on this?

When I do a flux error the error range given does not include the value calculated by the flux command.

How can I get XSPEC to automatically perform a set of commands on start-up (including loading my local models library)?

What is meant by a "named" model and when are names necessary?

Everytime I make a new plot, the plot window is placed in the center of the screen and takes control away from the XSPEC session window. Can I get the plot window to remain in the location I placed it, and to leave session window in control?

Jupyter notebook hangs when running steppar on more than one parameter with more than 31x32 steps. How can I fix this?

PyXspec output isn't being shown in Jupyter Notebook. How do I redirect PyXspec output to the notebook?

How do I plot two models fit to a spectrum?

How do I combine contour plots?

How do I handle the case where the background requires a different response to the source?

How do I include particle background?

How do I simulate a spectrum with particle background?

I have an ascii optical/UV fluxed spectrum which I would like to include in a fit in XSPEC. How do I do this?

How do I fit timing power spectra?

My local models library code calls functions from a third-party library. How do I get initpackage to include this library in the local models build?

I'd like to use the XSPEC model library in my program. What do I do?

In v11 I used to be able to include background models using a '/b' modifier. How do I do this in v12?

I need the v11 extend command.

Help! Help doesn't work.

If typing "help [command]" at the XSPEC prompt doesn't bring up a document window in either pdf or html format, you may need to edit your initial settings file ~/.xspec/Xspec.init. In the section "options and commands for displaying helpfiles," the USE_ONLINE_HELP setting determines if help will open online html web pages, or the distributed help pages in pdf format.

For online viewing, the html settings should simply be set to the name of your browser (in lower-case) unless you're on a Mac or Cygwin. For Mac's it should be set to "open" and for Cygwin "cygstart." Similarly the pdf viewer is set through the PDF_COMMAND variable. Suggested settings for various platforms are listed in the file.

Why doesn't Xspec report the reduced chi-squared at the end of a fit anymore?

Xspec no longer writes out the reduced chi-squared partly because you can easily calculate it for yourself, and also because it is a bit misleading. A reduced chi-squared of eg 1.1 means a very different thing if you have 20 degrees of freedom or if you have 2000.

You can't instruct Xspec itself to print out the reduced chi-sq, but you can easily calculate it yourself and display it, particularly if you're running from a script (Tcl for standard Xspec, Python for PyXspec). In standard Xspec the tclout stat command returns the total fit statistic and tclout dof returns the number of degrees of freedom (and the number of channels). Similarly in PyXspec these values can be obtained from Fit.statistic and Fit.dof. Then you just have to perform the division.

See the Statistics Appendix in the Xspec manual for further discussion about chi-squared and other statistical considerations.

How do I calculate the flux from only one component of my model? Can I get an error on this?

There is a new model component cflux which can be used in front of any component (or combination of components) for which you want to calculate the flux. This component makes the flux a parameter so its confidence interval can be calculated in the usual fashion.

When I do a flux error the error range given does not include the value calculated by the flux command.

This is possible and does not necessarily indicate that something has gone wrong. The flux error is calculated by generating parameter sets and for each parameter set calculating a flux. The fluxes are ordered and the eg 90% range derived by excluding the bottom and top 5%. The parameter sets are drawn from an estimate of the posterior distribution which assumes a multi-dimensional Gaussian with correlation matrix given by the matrix of second derivatives at the best fit. This may not be a good estimate if parameter space is complicated. We intend to replace this by a better method involving Markov Chain Monte Carlo.

How can I get XSPEC to automatically perform a set of commands on start-up (including loading my local models library)?

You can create a file xspec.rc in your ~/.xspec directory and place in it valid commands which will be executed upon start-up. If you've already built your local models library with the initpackage command, you can add "lmod mylibrary" (without the quotes) to xspec.rc and it will load everytime you start XSPEC (except on Cygwin).

For those maintaining XSPEC for a group of users, you can also add commands to be executed for every user on start-up. These should be placed in the file headas/spectral/scripts/global_customize.tcl and will be executed before the users' xspec.rc commands. See the subsection "Customizing XSPEC" in the manual's Xspec Overview for more information.

What is meant by a "named" model and when are names necessary?

One of the key enhancements of XSPEC12 is the ability to analyze with multiple models. Whenever you want to define more than one model, XSPEC requires names to distinguish among them. For example:

Define an unnamed model for detector source 1. This is also the way models are defined in XSPEC11. XSPEC12>model wa(po) Now define a second model with the name "anotherModel," to be applied to source detector 2. XSPEC12>model 2:anotherModel wa(ga) Define a third model, this time for source 1 which will render the first model inactive: XSPEC12>model 1:stillAnotherModel bbody See the model command help and its use of the active/inactive options for more information.

Everytime I make a new plot, the plot window is placed in the center of the screen and takes control away from the XSPEC session window. Can I get the plot window to remain in the location I placed it, and to leave the session window in control?

When you select the plot device (with the cpd command), choose "/xs" rather than "/xw". "/xs" will set up an xwindow for persistent use.

Jupyter notebook hangs. How can I fix this?

The Jupyter notebook buffer can hang when the output it too long. For example, running steppar on more than one parameter with more than 31x32 steps will cause the notebook to hang. The best workaround it to turn off chatter around the steppar command. For example:

You can still do a contour plot, or retrieve the parameter and/or statistic values (as you do with Fit.stepparResults('statistic')) afterwards.

Also note that the arrays returned by Fit.stepparResults are arranged differently than the scrolled output. When a 2-parameter steppar grid is run, the faster-varied parameter is performed like a raster scan (ie. 10.4 10.6 10.8 11. 11. 10.8 10.6 10.4). However, stepparResults returns the column in normal order: [10.4 10.6 10.8 11. 10.4 10.6 10.8 11.0] with the corresponding statistic and delta stat values re-arranged to match.

You can also get all the values by doing Plot('contour') and then retrieving Plot.x(), Plot.y(), and Plot.z() arrays. This returns things in a format that's particularly easy to pass to a 3rd-party plotting package such as matplotlib.

PyXspec output isn't being shown in Jupyter Notebook. How do I redirect PyXspec output to the notebook?

In older versions of Jupyter notebooks, the wurlitzer package was used to redirect output from the terminal to the notebook. Adding this to the top of your Jupyter notebook produced the PyXspec output in the notebook.

The wurlitzer package is no longer necessary on later versions of Jupyter notebook (beginning with version 6 at least). Starting with Jupyter notebook v7, the "%load_ext wurlitzer" command is actually detrimental and prevents redirection of the output to the notebook. PyXspec output should be shown in the notebook by default.

How do I plot two models fit to a spectrum?

Suppose we have separately fit two different models to a single spectrum and for illustrative purposes want to include them in the same plot. To do this we need to define two sources which we do as follows. Suppose the spectrum is example.pha and its response example.rsp.

This defines two sources, both using example.rsp as their response. We now load in both the models, with their parameter values as determined previously in the separate fits.

Now do the standard plot.

At this point the plot contains the data, the sum of the two models, and the two models. Obviously, we don't want the sum of the two models so we will set that to colour 0. To differentiate the models, change the colour on the second model.

To plot the the model fits without the data just use iplot foldmodel instead of iplot data. To plot both models in model space the following can be used:

How do I combine contour plots?

It is often useful to be able to superimpose contour plots based on multiple steppar or margin commands. This cannot be done within xspec but can be done by combining and editing files produced by xspec and plotting the result using qdp. Here is an example case of combining the results of steppar commands for the same model but with two different spectra. The model used was phabs(pow) and the datasets were file1.pha and file2.pha in the ftools/spectral/session directory. The steppar command was:

and the files were written out using

and

respectively. This creates files test1.pco, test1.qdp, test2.pco, test2.qdp. The qdp files contain the data and the pco files the commands used to make the contour plots.

Making combined plot requires combining the qdp data files and writing a new pco file. So, copy test1.qdp into a new file:

Now open an editor and read in testboth.qdp. On the first line replace test1.pco with testboth.pco. Go to the end of the file and insert test2.qdp. The inserted data will start with the lines:

Delete these and save the resulting file.

Now copy test1.pco into testboth.pco and open in an editor. If there are lines starting IMAG then delete them because they create the background image which will be confusing if multiple contours are being overplotted. The DG command is used to define data groups. The command

tells qdp that the first data group is from columns 1 to 26 in rows 1 to 26. This is the data from test1.qdp. Since the data from test2.qdp were appended the second data group is defined using the command

so this is added to the testboth.pco file. Finally take the CONT commands from test2.pco and add them to testboth.pco changing them all from CONT 1 to CONT 2. The color, style and width of the lines can be changed as necessary to distinguish the two sets of contours. To include a cross at the position of best fit for the second set of contours copy the LAB 1 command from test2.pco and change it to LAB 2. The resulting testboth.pco file will look something like:

Now create the plot using

How do I handle the case where the background requires a different response to the source?

Suppose we have a model for the background spectrum which requires a different response to that for the source spectrum. Read in the source and background spectra as separate files :

We set the response for the source :

Now we tell xspec that both these datasets will have a second model which must be multiplied by the back.rsp response matrix.

Set up the model for the source. Here we will take the simple case of an absorbed power-law :

Now we need to set up the background model for both datasets. In this case take the simple example of a single power-law

We have now set up xspec so that the source data is modeled by a source model multiplied by the source response plus a background model multiplied by the background response and the background data is modeled by the background model multiplied by the background response. The background models fitted to the source and background data are constrained to be the same.

How do I include particle background?

A particular case of background requiring a different response is particle background. This is assumed to depend on the instrumental response but not on the telescope effective areas. In xspec v11 and earlier a particle background model could be included by appending /b to additive components at the end of the model definition. These components were multiplied by the response file but not the arf. To do the equivalent in the current version of xspec suppose that our source.rsp in the example above can be split into source.rmf, the instrument response, and source.arf, the telescope effective area. To read the data in this case we do the following :

We can then define the source and background models as described when the background requires a different response to the source.

If separate rmf and arf files are not available then the v11 behavior can be replicated by using the script split_rsp_to_rmf_arf to split the response into a unit-normalized matrix and an effective area vector. If the response matrix is source.rsp, then the following command will generate the source.rmf and source.arf files required.

How do I simulate a spectrum with particle background?

Suppose we don't yet have a background spectrum but want to simulate a dataset which includes the particle background. We need a spectrum file - it doesn't matter what is in it - and the rmf and arf files.

Now define the source and background models and run fakeit eg :

I have an ascii optical/UV fluxed spectrum which I would like to include in a fit in XSPEC. How do I do this?

You can convert ascii files of fluxed spectra into XSPEC spectra and unit diagonal response matrices using the ftool ftflx2xsp.

How do I fit timing power spectra?

Adam Ingram and Chris Done note (see appendix A of http://arxiv.org/abs/1108.0789) the following method of fitting models to power spectra generated by powspec. The output of powspec can be written to a text file with four columns f, df, P, dP where f is the frequency and P the power spectrum. This should be converted to a text file with the four columns being f-df, f+df, 2*P*df, 2*dP*df. This file can be used as the input to flx2xsp to create a "spectrum" file and diagonal response to read into xspec. Plots in xspec of flux vs. energy are then actually of power vs. frequency (eg. ufspec will give frequency multiplied by power vs. frequency).

My local models library code calls functions from a third-party library. How do I get initpackage to include this library in the local models build?

The Makefile that initpackage creates for building your local models library is based on the template file heasoft-[ver]/Xspec/src/tools/initpackage/xspackage.tmpl. If you need to add a path to the third-party library's header files, add:   -I/path/to/your/3rdParty/library/include   to the HD_CXXFLAGS setting. Then:

For Mac with all versions of HEASOFT, or Linux with HEASOFT-6.26 or later:
To make sure the linker pulls in the library, further edit the xspackage.tmpl file by adding a "-l" flag for the library (e.g. -lgsl) in the HD_SHLIB_LIBS settings.

After completing your changes to xspackage.tmpl, reinstall it by typing "hmake" and "hmake install" from the heasoft-[ver]/Xspec/src/tools/initpackage directory.

For Linux/Unix with HEASOFT versions prior to 6.26:
The XSPEC executable itself should be relinked with the new library included. So, edit the file heasoft-[ver]/Xspec/src/main/Makefile by adding a "-l" flag for the library to the HD_CXXLIBS setting. Then from the same directory do:

After these modifications, you should be able to use initpackage and lmod in the normal way to build and load your local models library.

I'd like to use the XSPEC model library in my program. What do I do?

XSPEC models are contained in the library libXSFunctions, which can be linked into your program. The file Xspec/src/XSFunctions/xsFortran.h contains a collection of helper functions for interfacing with the XSPEC models and can be called in C, C++, and Fortran. See Appendix F for more information and a sample Makefile.

In v11 I used to be able to include background models using a '/b' modifier. How do I do this in v12?

In v12 it is possible to assign multiple detector responses to a spectrum and to define unique models for each detector number. This replaces and expands what was possible with the '/b' feature. For example, a second detector response can be added to spectrum 1: XSPEC12>response 2:1 backgroundResponse.pha and a corresponding model: XSPEC12>model 2:backgroundModel see the response and model commands for more information. An example is also available.

I need the v11 extend command.

The v11 extend command has been replaced by the more general energies command. With extend, the energy array was still partly constrained by the original response energies array. energies however allows you to replace the response energies with any arbitrary array, including one that can be read in from an ascii text file.