next up [*] [*]
Next: XSPEC Commands G-M Up: XSPEC commands Previous: Description of Syntax

Subsections

XSPEC Commands A-F

  
abund

Set the abundance table used in the plasma emission and photoelectric absorption models.



abund   <option>


where <option> is either angr, from Anders E. & Grevesse N. (1989, Geochimica et Cosmochimica Acta 53, 197), feld, from Feldman U. (1992, Physica Scripta 46, 202 except for elements not listed which are given grsa abundances), aneb, from Anders E. & Ebihara (1982, Geochimica et Cosmochimica Acta 46, 2363), grsa from Grevesse, N. & Sauval, A.J. (1998, Space Science Reviews 85, 161), or wilm from Wilms, Allen & McCray (2000, ApJ 542, 914 except for elements not listed which are given zero abundance), or lodd from the solar photospheric abundances in Lodders, K (2003 ApJ 591, 1220), or file filename, where filename is an ASCII file containing 30 lines with one number on each line. All abundances are number relative to H. The tables are :

 Element    angr       feld       aneb       grsa       wilm      lodd
    H      1.00e+0    1.00e+0    1.00e+0    1.00e+0    1.00e+0   1.00e+0
    He     9.77e-2    9.77e-2    8.01e-2    8.51e-2    9.77e-2   7.92e-2
    Li     1.45e-11   1.26e-11   2.19e-9    1.26e-11   0.00      1.90e-9
    B      1.41e-11   2.51e-11   2.87e-11   2.51e-11   0.00      2.57e-11
    Be     3.98e-10   3.55e-10   8.82e-10   3.55e-10   0.00      6.03e-10
    C      3.63e-4    3.98e-4    4.45e-4    3.31e-4    2.40e-4   2.45e-4
    N      1.12e-4    1.00e-4    9.12e-5    8.32e-5    7.59e-5   6.76e-5
    O      8.51e-4    8.51e-4    7.39e-4    6.76e-4    4.90e-4   4.90e-4 
    F      3.63e-8    3.63e-8    3.10e-8    3.63e-8    0.00      2.88e-8
    Ne     1.23e-4    1.29e-4    1.38e-4    1.20e-4    8.71e-5   7.41e-5
    Na     2.14e-6    2.14e-6    2.10e-6    2.14e-6    1.45e-6   1.99e-6
    Mg     3.80e-5    3.80e-5    3.95e-5    3.80e-5    2.51e-5   3.55e-5
    Al     2.95e-6    2.95e-6    3.12e-6    2.95e-6    2.14e-6   2.88e-6
    Si     3.55e-5    3.55e-5    3.68e-5    3.35e-5    1.86e-5   3.47e-5
    P      2.82e-7    2.82e-7    3.82e-7    2.82e-7    2.63e-7   2.88e-7
    S      1.62e-5    1.62e-5    1.89e-5    2.14e-5    1.23e-5   1.55e-5
    Cl     1.88e-7    1.88e-7    1.93e-7    3.16e-7    1.32e-7   1.82e-7
    Ar     3.63e-6    4.47e-6    3.82e-6    2.51e-6    2.57e-6   3.55e-6
    K      1.32e-7    1.32e-7    1.39e-7    1.32e-7    0.00      1.29e-7
    Ca     2.29e-6    2.29e-6    2.25e-6    2.29e-6    1.58e-6   2.19e-6
    Sc     1.26e-9    1.48e-9    1.24e-9    1.48e-9    0.00      1.17e-9
    Ti     9.77e-8    1.05e-7    8.82e-8    1.05e-7    6.46e-8   8.32e-8 
    V      1.00e-8    1.00e-8    1.08e-8    1.00e-8    0.00      1.00e-8
    Cr     4.68e-7    4.84e-7    4.93e-7    4.68e-7    3.24e-7   4.47e-7
    Mn     2.45e-7    2.45e-7    3.50e-7    2.45e-7    2.19e-7   3.16e-7
    Fe     4.68e-5    3.24e-5    3.31e-5    3.16e-5    2.69e-5   2.95e-5
    Co     8.60e-8    8.60e-8    8.27e-8    8.32e-8    8.32e-8   8.13e-8
    Ni     1.78e-6    1.78e-6    1.81e-6    1.78e-6    1.12e-6   1.66e-6
    Cu     1.62e-8    1.62e-8    1.89e-8    1.62e-8    0.00      1.82e-8
    Zn     3.98e-8    3.98e-8    4.63e-8    3.98e-8    0.00      4.27e-8

  
addcomp

Add a component to the current model.



addcomp   <comp #> <comp>


where <comp #> is the position in the model specification for the component and <comp> is its name. The user is prompted for parameter values for the component. Whenever it makes sense, XSPEC attempts to associate the component with the additive group of the component after it (see the model command for a description of additive groups). If you specify the component to be the last component in the model, then XSPEC will attempt to associate it with the overall multiplicative group. If it does not make sense to associated the component with an additive group, a new additive group is created.




Examples:

Suppose that the current model specification is ga+po, which using the show command would yield the description mo = gaussian[1] + powerlaw[2].


XSPEC>add 2 wab     !  gaussian[1]+wabs[2](powerlaw[3])
XSPEC>add 4 pha     !  (gaussian[1]+wabs[2](powerlaw[3]))phabs[4]
XSPEC>del 1     !  (wabs[1](powerlaw[2]))phabs[3]
XSPEC>add 2 zg     !  (wabs[1](zgauss[2]+powerlaw[3]))phabs[4]
XSPEC>del 3     !  (wabs[1](zgauss[2]))phabs[3]
XSPEC>add 4 bb/b     !  (wabs[1](zgauss[2]))phabs[3] + bbody/b[4]


  
addline

An auto-loaded Tcl script to add one or more lines to the current model in an optimum fashion.



addline   [<nlines>] [<modeltype>] [{fit|nofit}]


<nlines> additional lines are added one at a time. Line energies are set to that of the largest residual between the data and the model. For each line a fit is performed with the line width and normalization as the only free parameters. The default options are one line and a gaussian. The other <modeltype> that can be used is lorentz. If no third argument is given then the sigma and normalization of each line are fit. If ``nofit'' is specified then the fit is not performed but if ``fit'' is specified then all free parameters are fit.

  
arf

Read in one or more auxiliary response files (ARF). An ARF gives area versus energy and is used to modify the response matrix for a data set. The file must be in the OGIP standard format.



arf   [<filespec>...]


where <filespec> =:: [<data set num>] <filename>... and where <filename> is the name of the auxiliary response file to be used with the associated data set. <data set num> is the data set number for the first <filename> specified, <data set num> plus one is the data set number for the next file, and so on. If no <data set num> is given in the first <filespec> it is assumed to be 1. If no file specifications are entered, then none of the data set responses are modified. An error message is printed if the data set number is greater than the current number of data sets (as determined from the last use of the data command). A file name none indicates that no auxiliary response is to be used for that data set. No auxiliary response means that any incident spectrum will produce no counts for those particular channels. If a file is not found or cannot be opened for input, then the user is prompted for a replacement auxiliary response file. An <EOF> at this point is equivalent to none. See the data command for ways to completely remove the dataset from consideration.


Examples:

It is assumed that there are currently three data sets:


XSPEC>arf a,b,c     !  New files for the auxiliary response are given for all three files.
XSPEC>arf 2 none     !  No auxiliary response will be used for the second file.
XSPEC>arf,,d.fits     !  d.fits becomes the auxiliary response for the second file.


  
autosave

Set or disable autosave, which saves the XSPEC environment to a file periodically.





XSPEC>autosave <option>




where <option> is either off or a non-zero positive integer. If the option is off, then auto-saving is disable. If the option is N, the the XSPEC environment is saved every N commands. The saving of the environment is equivalent to the command save all xautosav.xcm, ie. both the file and model information is saved to the file xautosav.xcm in the local directory. Thus in case of an unexpected crash, the state of XSPEC before the crash can be restored with the command source xautosav.xcm. The default value for the auto-save option is 1.

  
backgrnd

Modify one or more of the files used in background subtraction.



backgrnd   [<filespec>...]


where <filespec> =:: [<data set num>] <filename>... and where <filename> is the name of the PHA file to be used for background subtraction. <data set num> is the data set number for the first <filename> specified, <data set num> plus one is the number for the next file, and so on. If no <data set num> is given in the first <filespec> it is assumed to be one (1). If no file specifications are entered, then none of the data set backgrounds are modified. An error message is printed if<data set num> is greater than the current number of data sets (as determined from the last use of the data command. A file name none indicates that no background subtraction is to be performed for that data set. If a file is not found or cannot be opened for input, then the user is prompted for a replacement background file. An <EOF> at this point is equivalent to using none as the background. See the data command for ways of removing the data set from consideration. The user is also prompted for a replacement if the background file has a different number of PHA channels than the associated data set. A warning will be printed out if the background detector ID is different than that of the associated data set. The current ignore status for channels is not affected by the bkgrnd command. (See the ignore and notify command). Note that background files have the same format as the PHA files used for the data command. If the background file is not in the (old) SF format, then any grouping specification will be overridden by the grouping in the source spectral file so that the source and background are binned in the same way.




Examples:

There are currently three data sets...


XSPEC>backgrnd a,b,c     !  New files for background subtraction are given for all three data sets.
XSPEC>backgrnd 2 none     !  No background subtraction will be done for the second data set.
XSPEC>backgrnd ,d     !  d.pha becomes the background for the second data set.


  
bayes

Set up for Bayesian inference.



bayes   [<option> | <parameter>] <prior type> <hyperparameters>


If a parameter number is given as the first argument, then this command sets up the prior for the specified model parameter. The supported priors are cons (constant) and exp (exponential). The cons prior requires no hyperparameters and the exp prior requires a hyperparameter giving the exponential decay scale. The log prior for the exp case is taken to be $-{\tt param/hparam}-\log{\tt hparam}$, where param is the fit parameter value and hparam the hyperparameter.

If the first argument to the bayes command is not a parameter number, then the three options allowed are cons, on, and off. The last two turn Bayesian inference on and off, respectively, and the first turns it on and gives all parameters a constant prior.

  
chain

Run a Monte Carlo Markov Chain.



chain   [rand] [stat] [burn <burn-in length>] [<length>]


If the argument rand is given the chain start point will be randomized. If not, then the current parameters are taken as the start. If the argument stat is given then instead of running a chain the statistics on currently active chains are output. The argument burn takes an argument specifying the number of steps to throw away before starting to store the chain. If the<length> given is the same as the last chain calculated or no length is specified then a chain will be run and stored as part of a set. If the length differs from previous chains then these will be discarded and a new set of chains will be started.

  
chatter

Control the verbosity of XSPEC.



chatter   <chatter level> <log chatter>


where <chatter level> and <log chatter> are integer values. The initial value for each argument is 10. Higher values will encourage XSPEC to tell the user more, lower values tell the user less, or make XSPEC ``quieter." <chatter level> applies to the terminal output, while <log chatter> controls the verbosity in the log file. Currently, the maximum chattiness is 25. Values below five should be avoided, as they tend to make XSPEC far too obscure. Some commands may temporarily modify the chattiness, such as the error command. A chattiness of 25 will generate a lot of debug output.




Examples:


XSPEC>chatter 10     !  Set the terminal chattiness to 10, same as the initial value.
XSPEC>chatter,,0     !  Set the chattiness for the log file to very low. This setting essentially disables the log file output.
XSPEC>chatter 5     !  Make XSPEC very quiet.
XSPEC>chatter 10 25     !  Restore the terminal chattiness to the initial level, while in the log file XSPEC will tell all (particularly when new data files are read in).


  
corfile

Reset the files used for background correction.



corfile   [<filespec>...]


where <filespec> is the same as for the backgrnd command. The correction file can be associated with a data set to further adjust the count rates. It is a PHA file whose count rate is multiplied by the current associated correction norm (see the cornorm and recornrm command) and then subtracted from the input uncorrected data. The correction norm is not changed by running the corfile command. Default values for the correction file and norm are included in the data PHA file. Unlike the background file, the correction data does NOT contribute to the measurement error. A file name of none is equivalent to no correction file used. If an input file can not be opened or found, an error message is printed and the user prompted for a replacement. As with the backgrnd command, the correction file is checked against the associated data set for number of channels, grouping status, and detector ID. The current ignore status for channels is not affected by the corfile command. Note that correction files have the same format as the PHA files used by the data command.


Examples:

It is assumed that there are currently three data sets:


XSPEC>corfile a,b,c     !  New correction files are used for all three data sets.
XSPEC>corfile 2 none     !  No correction will be done for the second data set.
XSPEC>corfile ,d     !  The 2nd file now uses d.pha as its correction.


  
cornorm

Reset the normalization used in correcting the background.



cornorm   [[<data set range>...] [<cor norm>]]...


where <data set range> =:: <first data set no.>-<last data set no.> is a range of data sets to which the correction is to be applied and <cor norm> is the value to be used for the normalization. A decimal point (.) is used to distinguish a correction norm from a single data set<data set range>. If no correction norm is given, then the last value input is used (the initial value is one (1)). If no range is given, then the last single range input is modified. (See the corfile command.)


Examples:

Assume that there are four data sets, all with associated correction files already defined, either by default in their PHA file, or explicitly by using the corfile command.


XSPEC>cornorm 1-4 1.     !  The correction norm for all four is set to 1.0.
XSPEC>cornorm 0. 1-2 0.3     !  The correction norm for the last input range (which was 1-4) is set to 0., then files 1 and 2 are reset to 0.3.
XSPEC>cornorm 4     !  File 4 has the correction also set to 0.3.
XSPEC>cornorm 1 4 -.3     !  Files 1 and 4 are set to -.3.
XSPEC>cornorm .7     !  File 4 (as the last input single range) is set to 0.7.


  
cosmo

Set the cosmology used (i.e., H0, q0, and $\Lambda_0$).



cosmo   [<H0> [<q0> [ <lambda0>]]]


where <H0> is the Hubble constant in km/s/Mpc,<q0> is the deceleration parameter, and <lambda0>is the cosmological constant. If the cosmological constant is non-zero then at present XSPEC requires that the universe is flat. In this case the value of <q0> will be ignored and XSPEC will assume that $\Omega_{matter} = 1 - lambda_0$. The default values are the WMAP standard: H0=70, $\lambda_0=0.73$ and a flat Universe.


Examples:


XSPEC>cosmo 100     !  Set H0 = 100 km/s/Mpc
XSPEC>cosmo ,0.     !  Set q0 = 0.
XSPEC>cosmo ,,0.7     !  Set a flat universe with lambda0 = 0.7


  
cpd

This command is an alias for setplot device.



cpd   {<PGPLOT device> | none}


  
data

Input one or more spectral data files.



data   <file spec>...


where <filespec> =:: [[<data group #>:]<data set #>] <filename>...

filename

If a particular file is not found or cannot be opened for input for some reason, then the user is prompted for a replacement file name. An<EOF> at this point is equivalent to typing none. The default extension for all files is .pha, so all other extensions, (e.g. .fak) must be entered explicitly. The default directory is the current user directory when XSPEC is invoked. When a new file is input, by default all its PHA channels are considered good channels for fitting and plotting purposes (see the ignore and notice commands), unless the file is replacing a previously-input file that had exactly the same number of total PHA channels, in which case the particular channels noticed are not modified.

If the file is an OGIP Type II PHA file containing multiple spectra, then the desired spectrum can be specified by appending {n} to the end of the filename, where n is the row number of the spectrum in the file. Alternatively, the spectrum can be specified by {column_name=value} where column_name is the name of a string column in the table.

XSPEC 11 allows ranges and wildcard characters for reading multiple spectra with a single command. Reading multiple spectra in this fashion is much more efficient (i.e. will execute much faster) than reading the same spectra separately. Given a file pha2data.pha containing, say, 64 spectra, examples of use are:

 XSPEC> data pha2data{14-26}
 XSPEC> data pha2data{*}
Reading multiple ranges with a single command (i.e. data pha2data {14-26,36-45}) is, however, not supported: it is in most cases more efficient to read the entire file if multiple ranges of data within a single file are needed.

If all of the spectra in the file have the same response (RESPFILE) and auxiliary response (ANCRFILE), background (BACKFILE) and correction (CORRFILE) files, specified with the indicated FITS keywords, XSPEC will use these files. It is also possible, however, to specify separate response/auxiliary files for each spectrum in the file. This is done by replacing the RESPFILE, (ANCRFILE, BACKFILE, CORRFILE) string valued keyword with a string-valued column with a response/auxiliary/correction/background filename for each row. Consult the FTOOLS package documentation for details of how to modify the file.

The individual spectral data files are created outside of XSPEC by detector-specific software. They are organized as XSPEC data files, but often referred to as PHA files. The PHA file contains such information as integration time, detector effective area, and a scaling factor that estimates the expected size of the internal background. The data file also contains the names of the default files to be used for background subtraction and for the detector sensitivity versus incident photon energy (the response and arf files). A data file has the total observed counts for a number of channels and a factor for the size of any systematic error. Each channel is converted to a count rate per unit area (assumed cm2). The default background file is used for background subtraction. An error term is calculated using Poisson statistics and any systematic error indicated in the file.

Any FITS NULL values will be converted to the value 1.e-32. This should have no practical effect because any channels with NULL values will presumably be marked as bad or otherwise ignored.

data set

Since XSPEC can fit simultaneously several sets of data (e.g., from multiple detectors), the data command allows multiple files to be input. Elsewhere in XSPEC, each set of data is referred to by its associated data set number. <data set #>, distinguishable from the list of file names because it is an integer, is the data set number for the first <filename> in the specification,<data set #>+1 is the data set number for the next file, and so on. If no <data set #> is given in the first<filespec> it is assumed to be one (1), so that the first data file input is data set 1, the next file is data set 2, and so on. A skipped-over argument indicates that the data set for that position (as input in an earlier invocation of data) will continue to be used. If the filename input is none, that data set is completely removed and any higher-number data sets are renumbered. The data command determines the current total number of data sets. If the command line is NOT terminated by a slash (/), the total number of datasets is the largest data set number given for any files explicitly input, or the largest value of a<data set num> argument. If the line is terminated by a slash (/), then the current number of data sets is the previous total number of datsets or the number as determined from the command line, whichever is greater. The exception to this rule is that if there are NO arguments to the data command, then the number of data sets is unchanged. (To remove all the data files from consideration would require a command like data 0.)

data group

XSPEC places each data set into a data group. Each data group has its own set of parameters for the defined model. These parameters can be either independent from data group to data group, or they can be linked across data groups using the standard XSPEC syntax. At present, each data group must have the same model, but some components can have normalizations set to zero. If no data group is specified, then the default is to place all data sets in the same data group.


Examples:


XSPEC>data a     !  The file a.pha is read in as the first (and only) data set.
XSPEC>data ,b     !  b.pha becomes the second data set, the first data set is unmodified (e.g. it is still a.pha).
XSPEC>data c 3 d,e,f     !  c.pha replaces a.pha as the first data set; d.pha, e.pha, and f.pha provide the, third, fourth, and fifth data sets.
XSPEC>data g/     !  g.pha replaces c.pha as the first data set; the slash (/) indicates that the 2nd through the 5th data sets remain as before.
XSPEC>data 2 none/     !  The string none indicates that the 2nd data set ( b.pha) is to be totally removed. The current total number of data sets thus becomes one less (4). The current data sets are g.pha, d.pha, e.pha, and f.pha.
XSPEC>data h,,     !  The current total number of data sets becomes 2, the current data sets are from h.pha and d.pha.
XSPEC>data     !  There is no change in the data status.
XSPEC>data 1     !  The number of data sets is set explicitly to one, that being from h.pha.
XSPEC>data 1:1 a 2:2 b 3:3 c     !  Read a.PHA into data group 1, b.pha into data group 2, and c.pha into data group 3.
XSPEC>data 1:1 a 1:2 b 2:3 c     !  Read a.pha and b.pha into data group 1, and c.pha into data group 2.
XSPEC>data a{3}     !  Read the third spectrum in the file a.pha.


  
delcomp

Delete components from the current model.



delcomp   <comp num range>


where <comp num range> is range of positions in the model specification of the components to be deleted.


Examples: Suppose that the current model specification is wa(po+ga+ga).


XSPEC>delcomp 3-4     !  Changes the model to wa(po).
XSPEC>delcomp 1     !  Changes the model to po


  
diagrsp

Diagonalise the current response matrix for ideal response.



diagrsp  


This command diagonalises the current response matrix. The response matrix is set so that the channel values are mapped directly into the corresponding energy ranges, based on the channel energies and energy response range of the current response matrix. This does not however change the effeciency (ie. effective area) as a function of energy stored for the current detector. Invoking this command will simulate a detector with prefect spectral resolution. If you wish to simulate a detector with prefect resolution and efficiency, use the dummyrsp command.

The previous response matrices can be reimplemented with the response command, with no arguments. Any use of the data and notice commands will replace the dummy response with a correct set of matrices.

  
dummyrsp

Create a ``dummy'' response, covering a given energy range.



dummyrsp   [<Low Energy> [<High Energy> [<# of ranges> [<log or linear> [<channel offset> [<channel width>]]]]]]


This command creates a dummy response matrix based on the given command line arguments, which will either temporarily supersede the current response matrix, or create a response matrix if one is not currently present. There are two main uses for this command: to do a ``quick and dirty'' analysis of uncalibrated data, and to examine the behaviour of the current model outside the range of the data's energy response.

In the first instance, one has a data set for which no response matrix is currently available. This command will create a diagonal response matrix with perfect efficiency. The response matrix will range in energy from <Low Energy> to <High Energy>, using<# of ranges> as the number of steps into which the range is logarithmicly or linearly divided. The detector channels are assigned to have widths of energy <channel width> (specified in keV), the lower bound of the first channel starting at an energy of <channel offset>. The response matrix is then set so that the channel values are mapped directly into the corresponding energy ranges. Then the data can be fit to models, etc., under conditions that assume a perfect detector response.

In the second instance, one can use this command to examine the current model outside the range of the energy response of the detector. When examining several aspects of the current model, such as plotting it or determining flux, XSPEC uses the current evaluation array. This, in turn, is defined by the current response files being used, which depend on the various detectors. For example, low energy datasets (such as those from the EXOSAT LEs) may have responses covering 0.05 to 2 keV, while non-imaging proportional counters can span the range from 1 to 30 keV. If the user wishes to examine the behavior of the model outside of the current range, then he or she temporarily must create a dummy response file that will cause the model to be evaluated from <Low Energy> to<High Energy>, using <# of ranges> as the number of steps into which the range is logarithmicly or linearly divided.

The initial default values for the arguments are 0.01 keV, 100 keV and 200 logarithmic energy steps. If one wishes only to set the energy response range, than the <channel width> argument may be omitted. In this case, or in the case where no data file has been read in, all entries of the dummy response matrix are set to zero. Under these circumstances the dummyrsp has no physically correct way of mapping the model into the data PHA channels, so the user should not try to fit-or plot-the data while the dummyrsp is active.

The previous response matrices can be reimplemented with the response command, with no arguments. Any use of the data and notice commands will replace the dummy response with a correct set of matrices, or with no response matrix if none was originally present.


Examples:


XSPEC>dummyrsp     !  Create the dummy response with the default limits, initially .01, 100, and 200 bins.
XSPEC>dummyrsp .001 1     !  Create a dummy response with 200 bins that cover the range from .001 to 1 keV.
XSPEC>dummyrsp ,,,500     !  The same range, but now with 500 bins.
XSPEC>dummyrsp ,,,,lin     !  The same range, but now with linearly spaced bins.
XSPEC>dummyrsp ,,,,,0.1     !  The same range, but now create a diagonal response matrix, with channel widths of 0.1 keV.
XSPEC>response     !  Restore any previous correct responses.


  
dump

Write out a history package of observed and model spectra.



dump   [<option>]


Two options are available : ecdata and model, with the same meaning that they have in the plot command. Plotting of unfolded spectra is possible with the XPLOT plotting program. A dump ecdata and a dump model write out all the necessary information into the history file.


Examples:


XSPEC>dump     !  The first dump command uses ecdata as default. It writes a history package containing the observed PHA spectrum and the folded model versus channel energy.
XSPEC>dump model     !  Write history package for the model spectrum in photons/cm2 s keV.


  
editmod

Add, delete, or replace one component in the current model.



editmod   [<delimiter>] <component1> <delimiter> <component2> <delimiter> ... <componentN> [<delimiter>]


where <delimiter> is some combination of (, +, *, and ), and <componentJ> is one of the models known to XSPEC. The arguments for this command should specify a new model, with the same syntax as the previous model, except for one component which may be either added, deleted, or changed to a different component type. XSPEC then compares the entered model with the current model, determines which component is to be modified (prompting the user if necessary to resolve ambiguities) and then modifies the model, prompting the user for any new parameter values which may be needed.




Examples:


XSPEC>mo wabs(po)     !   
XSPEC>ed wabs(po+ga)     !  This command will add the component gauss to model in the specified place and prompt the user for its initial parameters.
XSPEC>mo wabs(po+zg)     !   
XSPEC>ed po+zg     !  This command will delete the component wabs from the model, leaving the other components and their current parameter values unchanged.
XSPEC>mo wabs(po+po)     !   
XSPEC>ed wabs(po)     !  Here an ambiguity exists as to which component to delete. In this case XSPEC will print out the current model, showing the component number for each component, and then prompt the user for which component he wants deleted.
XSPEC>mo wabs(po+ga)     !   
XSPEC>ed wabs(po+zg)     !  The component gauss will be replaced by the component zgauss, and the user will be prompted for parameter values for the new component.


  
eqwidth

Determine the equivalent width of a model component.



eqwidth   [[RANGE <frac range>] <model component number>]... [err <number> <level> | noerr]


The command calculates the integrated photon flux produced by an additive model component (FLUX), the location of the peak of the photon spectrum (E), and the flux (photons per keV) at that energy of the continuum (CONTIN). The equivalent width is then defined as EW = FLUX / CONTIN in units of keV. The continuum is defined to be those other components of the selected model's additive group (see the model command). Thus, neither components in other additive groups nor the effect of any multiplicative components (e.g., absorption) are used in the calculation of the continuum or the equivalent width.

There are certain models with a lot of structure where, were they the continuum, it might be inappropriate to estimate the continuum flux at a single energy. The continuum model is integrated (from E(1-<frac range>) to E(1+<frac range>). The initial value of <frac range> is 0.05 and it can changed using the RANGE keyword.

The err/noerr switch sets whether errors will be estimated on the equivalent width. The error algorithm is to draw parameter values from the distribution and calculate an equivalent width. <number> of sets of parameter values will be drawn. The resulting equivalent widths are ordered and the central <level> percent selected to give the error range. The parameter values distribution is assumed to be a multivariate Gaussian centered on the best-fit parameters with sigmas from the covariance matrix. This is only an approximation in the case that fit statistic space is not quadratic. Note that fit must be run before using the error option and that the model cannot be changed (using model, editmod, addc, or delc) between running the fit and calculating the flux error.




Examples:

The current model is assumed to be M1(A1+A2+A3+A4+M2(A5)), where the Mx models are multiplicative and the Ax models are additive.


XSPEC>eqwidth 3     !  Calculate the total flux of component A2 (the third component of the model) and find its peak energy (E). The continuum flux is found by the integral flux of A1+A3+A4, using the range of 0.95E to 1.05E to estimate the flux.
XSPEC>eqwidth range .1     !  As before, but now the continuum is estimated from its behavior over the range 0.9E to 1.1E.
XSPEC>eqwidth range 0     !  Now the continuum at the single energy range (E) will be used.
XSPEC>eqwidth range .05 2     !  Now the component A1 is used as the feature, and A2+A3+A4 are used for the continuum. The range has been reset to the original value.
XSPEC>eqwidth 1     !  Illegal, as M1 is not an additive component.
XSPEC>eqwidth 7     !  Illegal, as there is no other additive component with A5 in its group to be used as the continuum.


  
error

Determine the confidence region for a model parameter.



error   [[stopat <ntrial> <toler>] [maximum <redchi>] [<delta fit statistic>] [<model param range>...]]...


where <model param range> =:: <first param>-<last param>determines the ranges of parameters to be examined, and <delta fit statistic> (distinguished from the model parameter indices by the inclusion of a period (.)), is the change in fit statistic used. Each indicated parameter is varied, within its allowed hard limits, until the value of the fit statistic, minimized by allowing all the other non-frozen parameters to vary, is equal to the last value of fit statistic determined by the fit command plus the indicated <delta fit statistic>. Note that before the error command is executed, the data must be fitted. The initial default values are the range 1-1 and the delta fit statistic of 2.706, equivalent to the 90% confidence region for a single interesting parameter. The number of trials and the tolerance for determining when the critical fit statistic is reached can be modified by preceeding them with the stopat keyword. Initially, the values are 10 trials with a tolerance of 0.01 in fit statistic. If a new minimum is found in the course of finding the error, then the calculation is aborted and control returned to the user. The maximum keyword ensures that error will not be run if the reduced chi-squared of the best fit exceeds <redchi>. The default value for <redchi> is 2.0.




Examples:

Assume that the current model has four model parameters.


XSPEC>error 1-4     !  Estimate the 90% confidence ranges for each parameter.
XSPEC>error 9.0     !  Estimate the confidence range for parameters 1-4 with delta fit statistic = 9.0, equivalent to the 3 sigma range.
XSPEC>error 2.706 1 3 1. 2     !  Estimate the 90% ranges for parameters 1 and 3, and the 1. sigma range for parameter 2.
XSPEC>error 4     !  Estimate the 1. sigma range for parameter 4.
XSPEC>error stop 20,,3     !  Estimate the 1-sigma range for parameter 3 after resetting the number of trials to 20. Note that the tolerance field had to be included (or at least skipped over).


  
exec

The command to execute a shell command.



exec   <shell command>


This command executes a shell (ie. an operating system) command, and then returns control to XSPEC after it is completed. Note that if your system is setup with the standard TCL distribution, shell commands entered at the XSPEC prompt will be executed automatically if they do not match any XSPEC or TCL command.

  
exit

The command to end the current XSPEC run.



exit  


After an exit, the current plot files are closed. An <EOF> will have an identical result.

  
extend

Extend the energy range over which the model is calculated.



extend   <high | low> <energy> <no. energies> <log | lin>


where high or low indicates whether the energy range is to be extended above or below that from the response matrix, <energy> is the maximum or minimum energy for the extension, <no. energies> is the number of energy bins to add, and log or lin is whether they should be spaced logarithmically or linearly. The defaults are to extend on the high end with logarithmic binning. Note that all response matrices in use are extended if necessary. This command is intended for use with convolution models which may need to have their input models calculated over a wide energy range. When the response matrix is read in again the extension is lost (note that this occurs when the notice command is used).




Examples:


XSPEC>extend high 50. 50     !  Extend the response energy to 50 keV in 50 logarithmic steps
XSPEC>extend low 0.1 10 lin     !  Extend the response energy down to 0.1 keV using 10 linear steps


  
fakeit

Produce PHA files with simulated data.



fakeit   [<file spec>...]


where <file spec> =:: [<file number>] <file name>... is similar to the syntax used in the backgrnd, corfile, and response command.

The fakeit command is used to create a number of artificial PHA files, where the current model is folded through response curves and then added to a background file. Poisson statistics can be included optionally. The integration time and correction norm are requested for each file. By default, the background, response, correction file, and numerical information are taken from the currently-defined data. If the argument line is empty, then it is assumed that the number of fakeit files produced is equal to the current number of data sets. The file names input as arguments are PHA files to be used as background. In these cases, their default response files and numerical data are used as the defaults when creating the associated fake data file. If none is given as an argument, then the user is prompted for the response file to be used and the default numerical data is set to 1., except the correction norm, which is set to zero. For each file, the user will be prompted for a PHA file name. If a background file is in use then this command will also fake a new background for each faked PHA file. Background files are given the same names as faked PHA files but with _bkg appended to the end of the root. After the PHA files are created, they are read in automatically as the current datafiles. The ignore status is completely reset.


Examples:

There are currently four data files, the second of which has a current background file CURRB.PHA and the last of which has no background being subtracted, equivalent to a background file none.


XSPEC>fakeit backa,,none 4     !  Four fake data PHA files are created. The first and second use BACKA.PHA and CURB.PHA for background, and their associated response files for the response. The third and fourth files will have no background files; the user will be prompted for the response file to be used. The 4 indicates that four data files will be created. Faked background files will also be created to go with the first 2 faked data files.


  
fit

Find the best fit model parameters for the current data.



fit   [<no iter> [<delta fit statistic>]]


where <no iter> is the maximum no. of iterations, and <delta fit statistic> is the critical change in the fit statistic. The default values are 10 and 0.01, respectively. After each iteration, the value of chi-squared and the parameters are printed.


Examples:


XSPEC>fit     !  Fit with the default number of iterations and critical delta chi-squared.
XSPEC>fit 60     !  Fit with 60 as the number of iterations.
XSPEC>fit ,,1.e-5     !  Fit with 1.e-5 as the critical delta.


  
flux

Calculate the flux of the current model between certain limits.



flux   [<lowEnergy> [<hiEnergy>]] [err <number> <level> | noerr]


where <lowEnergy> and <hiEnergy> are the values over which the flux is calculated. Initial default values are 2 to 10 keV. The flux is given in units of photons/cm2/s and ergs/cm2/s. The energy range must be contained by the range covered by the current data sets (which determine the range over which the model is evaluated). Values outside this range will be reset automatically to the extremes. Note that the energy values are two separate arguments, and are NOT connected by a dash. (see parameter ranges in the freeze command). The err/noerr switch sets whether errors will be estimated on the flux. The error algorithm is to draw parameter values from the distribution and calculate a flux. <number> of sets of parameter values will be drawn. The resulting fluxes are ordered and the central <level> percent selected to give the error range. The parameter values distribution is assumed to be a multivariate Gaussian centered on the best-fit parameters with sigmas from the covariance matrix. This is only an approximation in the case that fit statistic space is not quadratic.


Examples:

The current data have significant responses to data within 1.5 to 18 keV.


XSPEC>flux     !  Calculate the current model flux over the default range.
XSPEC>flux 6.4 7.0     !  Calculate the current flux over 6.4 to 7 keV.
XSPEC>flux 1 10     !  The flux is calculated from 1.5 keV (the lower limit of the current response's sensitivity) to 10 keV.


  
freeze

Do not allow indicated model parameters to vary. (See also thaw.)



freeze   [<param range>...]


where <param range> =:: {<param #> | <param #>-<param #>}. The indicated
model parameter or range of model parameters will be marked so they cannot be varied by the fit command by setting their associated<delta> to less than zero (see newpar command). By default, the range will be the last range input by either a freeze or thaw command.


Examples: Currently there are six parameters, initially all unfrozen.


XSPEC>freeze 2     !  Parameter 2 is frozen.
XSPEC>freeze 4-6     !  Parameters 4, 5, and 6 are frozen.
XSPEC>thaw 2 3-5     !  Parameters 2, 4, and 5 are thawed, parameter 3 is unaffected.
XSPEC>freeze     !  Parameters 3,4,5 are frozen (the last range input by a freeze or thaw command).


  
ftest

Calculate the F-statistic and its probability given new and old values of $\chi^2$ and number of degrees of freedom (DOF).



ftest   chisq2 dof2 chisq1 dof1


The new $\chi^2$ and DOF, chisq2 and dof2, should come from adding an extra model component to (or thawing a frozen parameter of) the model which gave chisq1 and dof1. If the F-test probability is low then it is reasonable to add the extra model component. WARNING : it is not correct to use the F-test statistic to test for the presence of a line (see Protassov et al astro-ph/0201547).


next up [*] [*]
Next: XSPEC Commands G-M Up: XSPEC commands Previous: Description of Syntax
Ben Dorman
2003-11-28