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.

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

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.

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.

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)

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,

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>
fakeitnone.

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, convolution, and mixing components (beginning
with v12.9.0) can act on individual components, on groups of components, or on
the entire model. Prior to v12.9.0, mixing transformations could apply only 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 thefreeze
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>
response2: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 rescalecovtorescale 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 fitand errorcommands 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
rebincan 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
deviceor
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 /xsand /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

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.

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 xmmpsfmixing 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:

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.