XSPEC is a command-driven, interactive program. You will see a prompt
XSPEC12>
whenever input is required. Command recall and inline editing are available using the arrow keys. XSPEC uses Tcl as its user interface, providing looping, conditionals, file I/O and so on. For further details of the Tcl syntax, consult the “Description of Syntax” section, the User Interface appendix, and links therein.
The string /* acts as an emergency escape back to the XSPEC prompt. This string in answer to any question should bounce XSPEC out of whatever it is doing and back to the command prompt.
Quick help: If you are uncertain about command syntax, typing a command followed by a “?” will print a one-line summary. The help command:
XSPEC12> help
without arguments will bring up the full XSPEC manual in a PDF document reader (e.g. AdobeÔ Acrobat Reader), or will open a browser to the XSPEC manual home page either locally or on the HEASARC site. See “Customizing XSPEC” later in this section to see how to select between these options, and how to assign a PDF reader and web browser to XSPEC. Typing
XSPEC12> help <command>
will display the manual section corresponding to <command>. Help for individual model components can be displayed by
XSPEC12> help model <modelName>
if all else fails you can e-mail your questions to the XSPEC team at
XSPEC commands can be divided into 6 categories: Control, Data, Model, Fitting, Plotting and Setting, as follows:
Control commands include items such as controlling logging, obtaining help, executing scripts, and other miscellaneous items to do with the program control rather than manipulating data or theoretical models.
Data commands load spectral data and calibration data such as backgrounds and responses, and specify channel ranges to be fit.
Model commands define and manipulate theoretical models and their parameters, and compute additional information such as fluxes or line identifications.
Fit commands initiate the fitting routines, control the parameter set, perform statistical tests and compute confidence levels.
Plot commands generate about 50 different kinds of 2-dimensional plots
Setting commands change a variety of XSPEC internals which control details of models, statistics, and fitting methods.
These command types are summarized below. For full details see Chapter 5.
In an interactive session, the command interpreter accepts the shortest unambiguous abbreviation for any command. Since the interpreter is built on the Tcl language, some possible XSPEC command abbreviations might coincide with both XSPEC and Tcl commands. In this case, the interpreter will print the multiple possibilities and stop. Command abbreviations may be specified in a start-up script ($HOME/.xspec/xspec.rc) – see Appendix A for details.
Inside a script, command abbreviations are not recognized. This behavior can be overridden but we do not recommended it: however, specific abbreviations can be defined in the custom startup script.
Operating-system commands can be given from within XSPEC simply by typing the command, as at the shell prompt: however, if wild cards are needed (e.g. ls *.pha) the operating system command must be preceded by syscall. Note that an XSPEC abbreviation which corresponds to a system command will run the latter.
Control commands include those for:
controlling parallel operations: parallel
writing program information: log, (save session to an ASCII file) script (record a set of commands), save (save commands needed to restore the current program state), autosave (automatically run the save command at specified intervals);
controlling program output: chatter (control the amount of program output), query (give an automatic response to prompts), tclout and tcloutr (create Tcl variables for manipulation in scripts)
displaying status information: show, time, and version
ending the session: exit (or quit)
displaying online help help and ‘?”. Help can be given either in summary, in specific manual pages, a manual section, or the entire manual.
The fit command will run a certain number of iterations and then query the user whether he or she wants to continue. While useful under most circumstances, the constant questioning can be a pain if one leaves XSPEC running and expects to find it finished when one gets back, or if one habitually runs scripts. One way around this problem is to reset the number of iterations before the question is asked by giving a single argument. For example,
XSPEC12> fit 100
will run 100 iterations before asking a question.
A more drastic solution is to use the query command.
XSPEC12> query yes
This will suppress all questions and assume that their answer is yes, while
XSPEC12> query no
will suppress all questions but assume that their answer is no.
The amount of output that XSPEC writes is set by the chatter command, which takes two arguments applying to the terminal and to the log file.
XSPEC commands can be written into a file and then executed by entering
XSPEC12> @filename
Alternatively, from the shell prompt
% xspec - filename &
for batch execution (remember to end the script in file filename.xcm with exit if you want the program to terminate after completion!). Note that the default suffix for xspec scripts is .xcm
The save command writes the current XSPEC status to a command file, which later can be run to reset XSPEC to the same configuration. XSPEC has a mechanism to save the current status automatically. This is controlled through the autosave command.
This command is very useful when reading a large number of data sets and/or fitting complicated models. If autosaving is operating (the default) then the equivalent of
XSPEC12> save all xautosav.xcm
is run after each command, so if a disaster occurs it is possible to recover.
Information on the current XSPEC status can be printed out using the show command. The time command writes out system-timing information, and the version command writes out the version number and the build time and date. Finally, XSPEC can be terminated with the exit or quit commands.
XSPEC is designed to allow complicated, multi-instrument analysis, so most commands can take arguments specifying more than one data set. Arguments in XSPEC are separated by either blanks or commas. A single argument can define a range. The ranges are delimited by a dash (–). A colon (:) is used to separate ranges (e.g., the phrase 1–2:11–24 refers to channels 11–24 in files 1 and 2).
XSPEC reads in spectra from spectral files using the data command. Several datasets may be specified in one command. Several datasets may be stored in a single file and accessed separately. A particular dataset in use may be replaced by another or dropped entirely. The input data file contains pointers to background, redistribution and auxiliary response files, but these pointers may be overridden by the backgrnd, response, and arf commands. All these commands have the same syntax as data. An auxiliary background file, called the correction file (an absolute subtraction with zero variance), also can be included using the corfile command. Its use is described in the section on fitting. The current response can be replaced by a diagonal version using diagrsp. A dummy response for testing purposes can be defined using dummyrsp.
PHA channels may be left out of fitting using the ignore command and included again using the notice command. These commands have a syntax allowing the same channels to be specified for more than one input file. The ignored and noticed ranges can be specified either as channels or as energies. If the command setplot wave has been entered, real ranges are interpreted as wavelengths.
The fakeit command is used to generate simulated data. The current response matrix and model (a model must be defined prior to using the fakeit command) are used to create fake data. The user is prompted for various options. To make fake data when only a response matrix is available, give the command
XSPEC12> fakeit none.
XSPEC will prompt the user for the response and ancillary filenames from which to build the simulated data. It is important to note that a model must be defined prior to issuing this command.
The most common use of XSPEC is to fit one or more data sets with responses to a particular model. However, it is often useful to be able to fit simultaneously several data sets with a model whose parameters can be different for each data set. A simple example would be a number of data sets that we expect to have the same model spectrum shape but different normalizations. XSPEC caters to this need through the use of data groups. When files are read in they can be labeled as belonging to a particular data group. When a model is defined a set of model parameters is allocated for each data group. These parameters can all vary freely or they can be linked together across data groups as required.
To set up data groups, the data command should be given as in the following example :
XSPEC12> data 1:1 file1 1:2 file2 2:3 file3
which sets up two data groups. The first data group comprises data sets from file1 and file2, and the second data group takes the data set from file3. Now when a model is defined, XSPEC will give two sets of model parameters, one for the first datagroup and one for the second.
XSPEC allows users to fit data with models constructed from individual components. These components may be either additive, multiplicative, mixing, or convolution. Multiplicative components simply multiply the model by an energy-dependent factor. Convolutions apply a transformation to the model component they operated on whereby the output can be affected by a range of input energies, such as in smoothing operations. Mixing components are two dimensional and designed to transform fluxes between different spatial regions (such as in projection). Multiplicative, and convolution components can act on individual components, on groups of components, or on the entire model, whereas mixing transformations apply to the whole model.
The model command defines the model to be used and prompts for the starting values of its parameters. The user also can set the allowed ranges of the parameter. Parameters can be linked to an algebraic function of the other parameters, and unlinked using the untie command. The value of an individual parameter can be changed with the command newpar (and the current setting queried with newpar 0). Parameters can be fixed at their current value with the freeze command and allowed to vary freely with the thaw command. Individual components can be added or subtracted from the model using addcomp, delcomp, and editmod. The plasma emission and photoelectric absorption models require an assumption about relative elemental abundances.
The flux command calculates the flux from the current model in the given energy range. This energy range must be within that defined by the current response matrix. If a larger energy range is required, then the energies command can be given to compute the model over the desired range. The lumin command calculates the luminosity for the source redshift given. The eqwidth command determines the equivalent width of a model component, usually a line. The user of either of these last two commands should read the help descriptions carefully. The Tcl script addline can be used to automatically add lines to a model. These can be identified using identify and modid.
New model components which can be described by a simple algebraic formula can be set up using mdefine and used in the same way as the standard models except they will run slower being interpreted rather than compiled.
Multiple models and responses can be assigned to a single spectrum. This generalizes and replaces the ‘/b’ technique of specifying background models in v11. In the FITS file format, a single response file can be associated with a spectrum either through a header keyword or a table column entry. XSPEC always assigns this response to a spectrum’s source number 1. The model command by default also creates new models for source number 1. The response command in tandem with model can be used to create additional sources. For example to add a background model to loaded spectrum 1, first load a 2nd response:
XSPEC12> response 2:1 resp2.rsp
then define a background model to apply to source 2:
XSPEC12> model 2:my_background_model_name wa(po)
This model will now apply to spectrum 1 and any other spectrum that has a response loaded for source 2. To apply a different background model to spectrum 2, load a response for source 3 rather than 2:
XSPEC12> response 3:2 another_response.rsp
XSPEC12> model 3:another_background_model ga
An arf can also be assigned to a particular source number and spectrum:
XSPEC12> arf 2:1 arf_file.pha
Source numbers do not need to be entered in consecutive order for a given spectrum, and gaps in numbering are allowed. Please see the individual model and response entries in the “XSPEC Commands” section for more information and examples.
The basic fit command is called fit. This command performs a minimization using the currently selected algorithm (default: Levenberg-Marquardt). fit takes arguments that are passed to the fitting method: by default, these are the number of iterations to execute before asking the user whether to continue, and the numerical convergence criterion.
A systematic model uncertainty can be included using the systematic command. The error or uncertain command calculates error bounds for one interesting parameter for the specified parameters and confidence levels. To produce multi-dimensional errors the steppar command is used to generate a fit-statistic grid. Two-dimensional grids may be expressed as contour plots (using plot contour). The model normalization can be set using the renorm command. The normalization of the correction file background can be set with cornorm. ftest and the Tcl script simftest can be used to calculate F-test probabilities.
Markov Chain Monte Carlo runs can be performed using the chain command with a useful Tcl script rescalecov to rescale the proposal distribution covariance if the Metropolis-Hastings algorithm is selected. The results can be analyzed using the margin command.
The 
statistic assumes that all the
spectral channels are Gaussian distributed and that the estimate for the
variance is uncorrelated with the observed counts. If the data are Poisson then
these are bad assumptions especially if there are small numbers of counts in a
channel. An alternative fit statistic, the C-statistic, should be used in this
case. The C-statistic can also provide confidence intervals in exactly the same
way as .
To use, give the command
XSPEC12> statistic cstat
and then use the fit
and error
commands as usual. An alternative (and deprecated) approach is to continue
using the statistic but change the weighting
to provide a better estimate of the variance in the small number limit. This
can be done using the weight
gehrels or weight
churazov commands. The latter is to be preferred.
The goodness-of-fit statistic can be set using the command statistic test. There are a number of options available. They can be interpreted using the goodness command, which utilizes Monte Carlo methods.
Often one does not want to use the full resolution of a spectrum, either because the channels over-sample the spectral resolution or because the S/N is low. XSPEC and the associated programs provide a number of ways of handling this. Firstly, the XSPEC command setplot rebin can be used to add channels together in the plot. It is important to realize that this effects only the plot and not the data being fitted.
Two FTOOLS are available to bin and group data for fitting purposes. RBNPHA bins up the data in a non-reversible manner and should only be used to ensure that the number of bins in the spectrum is the same as that in the response. GRPPHA is the tool of choice for grouping the data to get adequate S/N or number of counts in each channel. GRPPHA does not actually add together channels, but instead sets a flag which is read by XSPEC and causes XSPEC to sum the appropriate channels. If a data file is read with some grouping then XSPEC will apply the same operation to any background or response files used.
XSPEC plotting is currently performed using the PLT interface. There are two basic commands: plot and iplot. The plot command makes a plot and returns the user to the XSPEC prompt, while the iplot command leaves the user in the interactive plotting interface, thus allowing the user to edit the plot. A variety of different quantities may be plotted, including the data and the current model; the integrated counts; the fit residuals; the ratio of data to model; the contributions to the fit statistic; the theoretical model; the unfolded (incident) spectrum; the detector efficiency; the results of the goodness command; and the fit-statistic contours. All data plots can have an x-axis of channels, energy, or wavelength, which are specified with setplot channel, setplot energy, setplot wavelength respectively. A number of different units are available for energy or wavelength. The plotting device to be used is set using setplot device or cpd. Separate spectra may be added together and channels binned up (for plotting purposes only) using setplot group (and ungrouped with setplot ungroup) and setplot rebin. There is an option to plot individual additive model components on data plots, this option is enabled by setplot add and disabled by setplot noadd. The effective area can be divided out of data plots using setplot area (which option can be turned off using setplot noarea). Line IDs can be plotted using setplot id and turned off by setplot noid. A stack of PLT commands can be created and manipulated with setplot command, setplot delete, and setplot list. This command stack then is applied to every plot.
PLT is built on top of the PGPLOT package, which comes with a standard set of device drivers. Any machine running X-windows should support /xs and /xw, while xterm windows should support /xt. PGPLOT supports monochrome and color postscript and both landscape and portrait orientation with the drivers /ps, /cps, /vps, and /vcps.
The easiest way to make a hardcopy of an XSPEC plot is to use
XSPEC12> iplot
command and then at the PLT prompt to enter
PLT> hard /ps
This will make a file called pgplot.ps which can be printed. Alternatively, the sequence
XSPEC12> cpd <filename>/ps
XSPEC12> … plot commands …
XSPEC12> cpd none
will place the plots in a PostScript file <filename>.
The fit and goodness-of-fit test statistics are set using
the statistic
command. Other fit-minimization algorithms are available, and can be selected
using the method
command. The various fit methods require first and in some cases second
derivatives of the statistic with respect to the parameters. By default XSPEC
calculates these analytically, using an approximation for the second
derivatives. This may be changed by setting the USE_NUMERICAL_DIFFERENTIATION
flag in the user’s startup Xspec.init file. The weighting algorithm used to
calculate can be altered by the weight
command.
Other setting commands modify:
cosmological parameters used to calculate luminosity (cosmo)
solar abundances for 18 elements (abund)
photoionization cross-sections (xsect)
The xset command can be used as an interface for abund, cosmo, method, statistic, and xsect. Additionally, xset may set string expressions that are used by models, for example the path to, and version number of APEC atomic line calculations, or the coordinate system for surface brightness calculations used in the xmmpsf mixing model.
Ctrl-C can be used to break out of the data, chain, error, fit, and steppar commands. If a Ctrl-C is entered elsewhere, it will have no effect.
When a break is entered during the fitting commands (error, fit, and steppar), the fit will proceed until the end of the current fit iteration (ie. current lambda value when using Levenberg-Marquardt) before breaking. This is to ensure the program remains in a stable well-defined state. Therefore on slower machines, a user may notice a slight delay before the program actually breaks. Ctrl-C breaking is currently only implemented for the Levenberg-Marquardt fitting method.
Breaking is implemented for the data command primarily for users who load a large number of Type-II spectra with one data command. So if you enter
XSPEC12> data my_data{1-1000}
and decide it is taking too long to load, you can break out at any time. However, if you do choose to break, all spectra loaded from that particular data set will be lost. For example, if the command below is entered and a Ctrl-C is sent while the spectra from my_data2 are loading, the 50 spectra from my_data1 will be retained while none will be from my_data2:
XSPEC12> data my_data1{1-50} mydata2{1-50}
The XSPEC environment can be customized using two separate files, both of which are searched for in the directory
$HOME/.xspec
The first file, Xspec.init contains a number of settings that control items in XSPEC. An abridged version of this file is reproduced below.
################################################
#
# options and commands for displaying helpfiles
#
USE_ONLINE_HELP: true
# Recognized local help formats: html pdf
# This is ignored when using online help
LOCAL_HELP_FORMAT: html
# Recommended command for Adobe Acrobat version 7 and later:
# PDF_COMMAND: acroread -openInNewWindow -tempFileTitle
# Recommended command for Adobe Acrobat prior to version 7:
# PDF_COMMAND: acroread -useFrontEndProgram -tempFileTitle
# Recommended command for Mac PDF viewing
PDF_COMMAND: open
# Recommended command for Cygwin PDF viewing
# PDF_COMMAND: xpdf -q
# Recommended command for Mac html
HTML_COMMAND: open
# HTML_COMMAND: firefox
#################################################
#
# setting for GUI mode. The code requires that the GUI setting
# starts with a 't' (case-insensitive) otherwise GUI mode is false
# and the command line mode is used.
#
GUI: false
#
# user-definable setting for the dummy response. Arguments required
# begin-range end-range, number of bins, logarithmic/linear. Defaults
# are {0.1,100,200,log} respectively. Setting for bin type must be "linear"
# if linear bins are to be created.
#
DUMMY: 0.1 50. 1000 log
#
# Chatter Level: Console chatter level then log chatter level. Currently (4/2001)
# logging has not been reimplemented.
#
CHAT: 10 10
#
# photo absorption cross section table setting.
# possible values are vern, bcmc, obmc.
XSECT: bcmc
#
# solar abundance table indicator. Hard coded solar abundance vector. Choices are
# 'feld' Feldman, U., 1992. Physica Scripta, 46, 202.
# 'angr' is from Anders, E. & Grevesse, N., 1989. Geochimica and Cosmochimica Acta 53, 197.
# 'aneb' is from Anders, E. & Ebihara, 1982. Geochimica and Cosmochimica Acta 46, 2363.
#
ABUND: angr
#
# fitting method (leven | anneal ...)
#
METHOD: leven
#
# statistic to be minimized (chi | cstat)
#
STATISTIC: chi
#
# weighting technique (standard | gehrels | churazov | model )
#
WEIGHT: standard
#
# If true, fitting algorithm will calculate parameter derivatives
# numerically. If false, a faster analytic expression will be used,
# if applicable to the current fitting statistic.
#
USE_NUMERICAL_DIFFERENTIATION: false
#
# cosmology parameters ( H0, q0, lambda0 )
#
COSMO: 70. .0 .73
#
#
# Default graphics package (PLT is currently the only option).
#
GRAPH: plt
#
# Default plotting device (e.g. for PGPLOT)
#
PLOTDEVICE: /null
#
# Y-axis plotting units when in setplot wave mode (angstrom, hz)
#
WAVE_PLOT_UNITS: angstrom
#
# User scripting directory
#
USER_SCRIPT_DIRECTORY: $HOME/.xspec
#
# Default setting for parameters' fit delta values.
# Valid options are:
#
# fixed
# proportional <fraction of parameter value>
#
# If set to 'fixed', the default values come from the settings in the
# model.dat model definition file.
#
FIT_DELTAS: proportional .01
A copy of this file is placed in the $HOME/.xspec directory on XSPEC12’s first start-up or when it is not found. After this users can modify settings such as default cosmology or the energy range for dummy response for their own requirements.
This is also the place where users can select if they want to view PDF help files from the XSPEC distribution or HTML either locally or from the HEASARC site. Setting USE_ONLINE_HELP to true uses the remote HTML files while false will use either PDF or HTML local files depending on the value of LOCAL_HELP_FORMAT.
The PDF_COMMAND and HTML_COMMAND entries determine which applications are run for the two viewing cases. The HTML_COMMAND value should typically just be the name of a web browser, or “open” for Mac OS X users. The default settings for the PDF_COMMAND entry are what work best for launching Adobe Acrobat Reader 7.0.x on Linux/Unix systems. For those launching earlier versions, the “-openInNewWindow” flag should be replaced with “-useFrontEndProgram”. For Mac users, again we recommend the entire entry simply be replaced with “open”.
The second file that is searched for is the xspec.rc file. This contains users’ own customizations, for example Tcl or XSPEC command abbreviations, packages to be loaded on startup, or Tcl scripts containing procedures that are to be executed as commands. Please consult Appendix A and references/links therein for details of Tcl commands and scripting.
When an XSPEC build is intended for many users across a system, it is also possible for the installer (or whoever has write access to the distribution and installation areas) to globally customize XSPEC. This is done through the file global_customize.tcl, located in the …/Xspec/src/scripts directory. (This was done in the xspec.tcl file prior to v12.2.1) Any of the customizations mentioned above for the individual’s own xspec.rc file can also be placed in the global_customize.tcl file. After making the additions, run “hmake install” out of the …/Xspec/src/scripts directory in order to copy the modified global_customize.tcl file to the installation area. This additional code will be executed for all users upon startup, BEFORE any of their own customizations in their xspec.rc files.