next up [*] [*]
Next: XSPEC V11.3 Models Up: XSPEC commands Previous: XSPEC Commands N-S


XSPEC Commands T-Z


Write internal xspec data to a tcl variable. This facility allows the manipulation of xspec data by tcl scripts, so that one can, for example, extract data from xspec runs and store in output files, format xspec output data as desired, use independent plotting software, etc.

tclout   <option> [<par1>] [<par2>] [<par3>]

tclout creates the tcl variable $xspec_tclout, which can then of course be set to any named variable. The allowed values of <option>are :

? the valid options. Does not set $xspec_tclout.
areascal n s|b the areascal value(s) for s(ource) or b(background) dataset n.
arf n the auxiliary response filename for dataset n.
backgrnd n the background filename for dataset n.
backscal n s|b the backscal value(s) for s(ource) or b(background) dataset n.
chatter current xspec chatter level.
compinfo n name, 1st parameter number and number of parameters of model component n.
datagrp number of datagroups.
datasets number of datasets.
dof degrees of freedom in fit.
energies n energy array for dataset n.
eqwidth n last equivalent width calculated for dataset n.
error n last last confidence region calculated for dataset n.
expos n s|b the exposure value for s(ource) or b(background) dataset n.
filename n filename corresponding to dataset n.
flux n last model flux or luminosity calculated for dataset n.
ftest the result of the last ftest command.
genpop n the genetic algorithm population for parameter n.
idline e d possible line IDs within the range [e-d, e+d].
model description of current model.
modcomp number of model components.
modpar number of model parameters.
modval n calculated model values for dataset n (in ph/cm2/s/bin).
noticed n range (low,high) of noticed channels for dataset n.
param n (value,delta,min,low,high,max) for model parameter n.
peakrsid n {lo, hi} energies and strengths of the peak residuals (+ve and -ve) for the dataset n.
  Optional arguments lo, hi specify an energy range in which to search.
pinfo n parameter name and unit for parameter n.
plink information on parameter linking for parameter n. This is in the form true/false
  (T or F) for linked/not linked, followed by the multiplicative factor and
  additive constants if linked.
plot option array n arrays from a plot command for plot group n. The array options are x,xerr,y,yerr.
plotgrp number of plot groups.
query the setting of the query option.
rate count rate, uncertainty and the model rate for the specified dataset number.
response n the response filename for dataset n.
solab solar abundance table values.
stat value of statistic.
varpar number of variable fit parameters.
xflt n the XFLT#### keywords for dataset n.


XSPEC>data file1
XSPEC> model pha(po)
XSPEC> fit
XSPEC>tclout stat        
XSPEC>scan $xspec_tclout "%f" chistat
XSPEC>tclout param 1
XSPEC>scan $xspec_tclout "%f"  par2
XSPEC>tclout param 2
XSPEC>scan $xspec_tclout "%f"  par3
XSPEC>tclout param 3

In this example, scan is a tcl command that does a formatted read of the variable $xspec_tclout. It reads the first floating point number ("%f") into the variable given by the last argument on the line. This sequence creates a simple model, fits it, and then writes the $\chi^2$ statistic and the three parameters to tcl variables $chistat, $par1, $par2 and $par3. These can now be manipulated in any way permitted by tcl.


Allow indicated parameters to vary. (See also freeze.)

thaw   [<param range>...]

where <param range> =:: {<param #> | <param #>-<param #>}. The indicated parameter, or range of parameters, will be marked as variable by the fitting commands, by setting their associated <delta> to greater than zero (see newpar command). (Note that parameters with <delta> values equal to zero are not affected. The newpar command must be used to change these.) By default, the range will be the last range input by either a freeze or thaw command. See the freeze examples for an example of the use of the thaw command.


Determine the expected line equivalent width of a fluorescent line.

thleqw   [<line energy> <line fluorescent yield> <absorption edge energy> <upper energy limit> <bin number> <log or lin> <max edge depth>]

The thleqw command integrates the photon flux absorbed in an edge with the maximum depth from the edge energy to the upper energy limit. To get good resolution in the edge, the command uses the dummyrsp command with the edge energy as low energy, the upper energy limit as high energy and the bin number for the number of ranges (see dummyrsp command). The calculation for the edge absorption is done in the same way as in the edge command. The fluorescent yield is used to calculate the photon flux going into a fluorescent line emission. The continuum flux is calculated in the same way as it is in the eqwidth command. No lines are added to the continuum. This model assumes a spherically symmetric distribution of absorbing material around the X-ray source with a column density obtained by the wabs model. The defaults are 1.0 keV, 0., .01 keV, 100. keV, 200, and 0.0, which gives 0 for the equivalent width. They are chosen this way since the dummyrsp command defaults are 0.01 keV, 100. keV and 200. Since the thleqw command uses dummyrsp, the old response must be read in again when working further on the same spectrum.


XSPEC>thl 6.4,.34,7.1,20.,,,.015     !  Calculate the expected equivalent width for a line at 6.4 keV with a fluorescent yield of 34%. The absorption edge is integrated from 7.1 keV to 20. keV in 200 steps. The maximum depth is .015.
XSPEC>thleqw ,,,,,,100     !  As before, but with 100 steps
XSPEC>thleqw     !  As before.

Don't forget to read the response file in again if you want to do further work on the same data.


Get some information about the program run time.


Provides the following:

		 		elapsed real time

elapsed CPU time
buffered I/O count
direct I/O count
page fault count


A synonym for error.


Untie the specified parameter from any links to other parameters.

untie   <param #>


Change the weighting function used in the calculation of chi-squared.

weight   [standard | gehrels | churazov | model ]

Standard weighting uses $\sqrt{N}$ or the statistical error given in the input spectrum. Gehrels weighting uses $1+\sqrt{N+0.75}$, a better approximation when N is small (Gehrels, N. 1986, ApJ 303, 336). Churazov weighting uses the suggestion of Churazov etal (1996, ApJ 471, 673) to estimate the weight for a given channel by averaging the counts in surrounding channels. Model weighting uses the value of the model, not the data, to estimate the weight.


Open a file for outputting history records. [deprecated]

xhistory   {<filename> | none}

where <filename> is the name of the file to be opened for output. The string none will close the current history file. The history file produces SF format packages that can be read by other programs. For example, the results of the XSPEC steppar command are placed in the steppar package, which in return is used by the XPLOT program to plot confidence contours. The history file is not directly human-readable. A more printable recounting of an XSPEC session is produced with the log file (see the log command). Currently implemented history packages:

data files produced by data, fakeit
assoc. files   data, backgrnd, response, corfile, fakeit
channels   data, ignore, notice
model   addcomp, model, delcomp
param def   addcomp, model, define, delcomp, newpar, addcomp, model, freeze
fit   fit
steppar   steppar
error   error
equiv width   eqwidth
flux   flux
flum   lumin
spectrum   dump ecdata
photon   dump model
time   time


Change the photoelectric absorption cross-sections in use.

xsect   [bcmc|obcm|vern]

The three options are bcmc, from Balucinska-Church & McCammon (1992; Ap.J. 400, 699) with a new He cross-section based on (1998; Ap.J. 496, 1044); obcm, as bcmc but with the old He cross-section, and, vern, from Verner et. al. (1996 Ap.J.). This changes the cross-sections in use for all absorption models with the exception of wabs.


Modify a number of XSPEC internal switches.

xset   [ abund | cosmo | forcecalc | mdatadir | method | statistic | weight | xsect | <string_name> ] [ <options> | <string_value> ]

The arguments abund, cosmo, method, statistic, weight, and xsect just run the appropriate XSPEC commands. forcecalc on forces XSPEC to calculate the model for every dataset. forcecalc off (the default) ensures that if two datasets have the same energy bins then the model is only calculated once for these energies and the results are just copied for the other dataset. This is fine except for the few models which depend on information about the dataset in addition to the energy ranges. mdatadir changes the directory in which XSPEC searches for model data files. You probably don't want to change this. The <string_name> option can be used to pass string values to models. XSPEC maintains a database of <string_name>, <string_value> pairs created using this command. Individual model functions can then access this database. Note that xset does no checking on whether the<string_name> is used by any model so spelling errors will not be trapped.

To access the <string_name>, <string_value> database from within a model function use the fortran function fgmstr. This is defined as character*128 and takes a single argument, the string name as a character*128. If the <string_name> has not been set then a blank string will be returned.


XSPEC>xset neivers 2.0     !  Set the NEIVERS variable to 2.0
XSPEC>xset     !  List the current string variables
XSPEC>xset apecroot /foo/bar/apec_v1.01     !  Set the APECROOT variable
XSPEC>xset forcecalc on     !  Force the explicit calculation of models for all datasets

next up [*] [*]
Next: XSPEC V11.3 Models Up: XSPEC commands Previous: XSPEC Commands N-S
Ben Dorman