XSPEC is a command-driven, interactive program. The user 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 this manual’s “Description of Syntax” section, the “User Interface” appendix, and links therein.
How to return to the XSPEC> prompt
The string /* acts as an emergency escape back to the XSPEC prompt. If one gives this string in answer to any question then one should be bounced out of whatever one is doing and returned to the XSPECprompt.
Quick help: If the user is uncertain about command syntax, typing a command followed by a “?” will print a one-line summary of the command syntax. Typing
help
without arguments will bring up the full XSPEC manual in a pdf document reader (e.g. AdobeÔ Acrobat Reader) for offline viewing, or will open a browser to the XSPEC manual homepage online. See “Customizing XSPEC” later in this section for details on how to select online or offline viewing, and how to assign a pdf reader and web browser to XSPEC. Typing
help <command>
will display the manual section corresponding to command. Help for individual theoretical model components can be displayed by
help model <modelName>
XSPEC commands can be divided into 6 categories: Control, Data, Model, Fitting, Plotting and Setting commands, 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 allow the user to change the way used in the models are calculated or fit, such as abundance ratios or photoionization cross-sections, or changing the statistic or fitting method.
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. User’s command abbreviations may be specified in a start-up script ($HOME/.xspec/xspec.rc) – see §3.13 and Appendix A for details.
Inside a script, command abbreviations are not recognized. This behavior can be overridden but it is not recommended to do so: however, specific abbreviations the user wishes to use can be specified in the user’s custom startup script.
Operating-system commands can be given from within XSPEC simply by typing the command, as at the shell prompt: however, if wildcards are needed (e.g. ls *.pha) the operating system command must be preceded by syscall.
Control commands include those for:
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 (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.
Query, chatter and shutting XSPEC up (somewhat)
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 on the fit command. For example,
fit 100
will run 100 iterations before asking a question.
A more drastic solution is to use the query command.
query yes .
This will suppress all questions and assume that their answer is yes, while 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.
One can write XSPEC commands into a file and have them executed by entering
XSPEC> @filename
at the XSPEC prompt.
Also, one may enter from the shell prompt
% xspec - filename &
for batch execution (remember to end the script in file filename 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
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.
Data 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).
Reading data and modifying calibration and auxiliary files
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 data set 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.
Controlling channels being fitted
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 one must define a model 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 labelled 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 :
XSPEC> 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.
Model Commands
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 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 reponse energies can be restored with the energies reset option.) 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 command addline can be used to automatically add lines to a model. These can be identified using identify and modid.
Models with multiple responses and background models
Beginning with XSPEC 12.3.0, it is possible to assign additional models and responses to spectra from type I and type II OGIP standard files. Previously this capability only existed for Integral/SPI data, and it now generalizes and replaces the ‘/b’ technique of specifying background models in XSPEC v11.
In the OGIP 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 though can create additional sources. For example to add a background model to loaded spectrum 1, first load a 2nd response:
response 2:1 resp2.rsp
then define a background model to apply to source 2:
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:
response 3:2 another_response.rsp
model 3:another_background_model ga
An arf can also be assigned to a particular source number and spectrum:
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.
Fitting Commands
The basic fit command is called fit. This command performs a minimization using the currently selected algorithm (default: Levenberg-Marquadt). 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 provides calculation of F-test values and probabilities.
What to do when you have small numbers of counts
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 there
are small numbers of counts in a channel these will not be true. An alternative
statistic, the C-statistic, can be used in this case. The C-statistic now in
use does provide a goodness-of-fit if there are enough counts and this can be
checked using the goodness command which uses Monte Carlo ethods. This
C-statistic can also provide confidence intervals in exactly the same way as
To use, give the command
stat cstat
and then use the fit and error commands as
usual. An alternative 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.
Often one does not want to use the full resolution of a spectrum, either because the channels oversample 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.
Plotting Commands
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; 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. 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. 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 X-windows terminal should support /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 of making a hardcopy of an XSPEC plot is to use the
XSPEC12>iplot
command and then at the PLT prompt to enter
XSPEC12>hard /ps
This will make a file called
pgplot.ps
which can be printed. Alternatively, the sequence
XSPEC12>cpd <filename>
XSPEC12> … plot commands …
XSPEC12> cpd none
Will store a set of plots generated by the commands in the file <filename>. Color output and portrait orientation are also supported.
The fit statistics available within XSPEC are the
and C statistics: the statistic
command specifies which one is to be used. Other fit-minimization algorithms
are available, and can be selected using the method command. The
weighting algorithm used to calculatecan
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 such as in xmmpsf.
A new feature implemented for XSPEC 12 is the ability of the user to break out of certain time-consuming commands by entering Ctrl-C. This feature is currently available for the following commands only: data, chain, error, fit, and steppar. 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 one enters “data my_data{1-1000}” and decides it is taking too long to load, they may break out at any time. However, if they 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}
Users may customize their XSPEC environment 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.
# XSPEC12 Initial settings file
# Valid setting lines consist of two strings in the format Key: Value
# leading and trailing blanks are ignored for the key, leading blanks/tabs ignored for
# the value. Invalid settings (no colon) are ignored, keys valid in format but not
# implemented are simply read but not used.
################################################
#
# User default local model directory
# example code may be found in the source tree at:
LOCAL_MODEL_DIRECTORY:${PATH_TO}/myLocalModelsDir
################################################
#
# options and commands for displaying helpfiles
#
USE_ONLINE_HELP: false
PDF_COMMAND: acroread -openInNewWindow -tempFileTitle
HTML_COMMAND: mozilla
#################################################
#
# 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. 50 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.
# 'file' is from a file read in by the user, but is not yet implemented (4/2001)
#
ABUND: angr
#
# fitting method (leven | anneal ...)
#
METHOD: leven
#
# statistic to be minimized (chi | cstat)
#
STATISTIC: chi
#
# weighting technique (standard | gehrels | churazov | model )
#
WEIGHT: standard
#
# 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
#
# User scripting directory
#
USER_SCRIPT_DIRECTORY: $HOME/.xspec
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 from the online manual pages. The latter may be the better option if the user is running XSPEC off of a remote system. The online files are also naturally easier to modify with any corrections and additions. Setting the USE_ONLINE_HELP value to true or false determines which help files to access.
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 XSPEC12 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 for all users. This is now 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.