gain | fit |
gain | nofit |
gain | <data set #> <slope> <intercept> |
The initial default <data set #> is 1; later, the default is the number of the file last modified. Initially, all responses are assumed to have nominal gains, determined implicitly by the data in the response files. This is equivalent to a <slope> of 1 and an<intercept> of zero. If the fit argument is given then the <slope> and <intercept> for each dataset will be added to the model parameters and can be fit for. The nofit argument switches off the fitting and leaves the gain at the current values of the parameters. Unless gain fit is in use the gain is automatically reset to nominal whenever a new data file or response file is defined for that file number, but not by any use of the ignore, notice, or dummyrsp commands.
Examples:
We assume that the current response for data set one is rspfile.
XSPEC>gain 1 0.98 | ! | The first data set's response is adjusted with a slope of 0.98. | |||
XSPEC>gain 1,,.03 | ! | The offset also is moved now by 0.03 channels. | |||
XSPEC>gain ,, 1 0 | ! | Now the response is explicitly restored to the nominal value. | |||
XSPEC>gain ,, 1.1 -.5 | ! | Now it is adjusted, with slope 1.1 and offset -0.05. | |||
XSPEC>response 1 none | ! | The response is removed. | |||
XSPEC>response rspfile | ! | rspfile.rsp is used as the response, the gain is reset to nominal. |
genetic | <option> <value> |
Set parameters used in the PIKAIA genetic global minimization algorithm (see `method' for further details). For details see Charbonneau, P., 1995, Ap.J. Suppl, 101, 309.
Option can take the following values.
npop | Change the size of the population. |
ndigits | Change the encoding accuracy. |
pcross | Change the crossover rate. |
imutate | Change the size of the population. |
pmutate | Change the initial mutation rate. |
pmutmin | Change the minimum mutation rate. |
pmutmax | Change the maximum mutation rate. |
fdif | Change the fitness differential. |
irepro | Change the reproduction plans. |
ielite | Change the elitism. |
iverbose | Change the verbosity. |
Perform a Monte Carlo calculation of the goodness-of-fit.
goodness | [<# of realizations>] [sim | nosim] |
This command simulates <# of realizations> spectra based on the model and writes out the percentage of these simulations with the fit statistic less than that for the data. If the observed spectrum was produced by the model then this number should be around 50%. This command only works if the sole source of variance in the data is counting statistics. The sim/nosim switch determines whether each simulation will use parameter values drawn from a Gaussian distribution centered on the best fit with sigma from the covariance matrix. The sim switch turns on this option, nosim turns it off in which case all simulations are drawn from the best-fit model.
Spool the current plot to the printer.
hardcopy |
This command takes what ever is the currently display in you plot window, writes it to a postscript file, and then sends it to a printer using the unix lpr command. It will thus be printed on whatever printer lpr uses as your default printer.
help | [<topic list>] |
The help command uses the XHELP interactive help facility. The optional
topic list can be used to go directly to a particular topic and sub-topic.
The XHELP facility has a number of special input characters used to access
different sub-topics. The string ?? will produce a summary of these
sub-topics. To exit back to XSPEC, use an <EOF> or type <RETURN>until you leave the help facility.
Examples:
In the following example, only the results of the initial invocation (in response to the XSPEC>prompt) are given. Subsequent XHELP characters and sub-topic names can be given, until control is returned to XSPEC via the <EOF>.
XSPEC>help | ! | Go to the top of the help file. | |||
XSPEC>help command fit | ! | Go to the help text for the fit command. | |||
XSPEC>he com he exam | ! | Go to the example text for the help command. | |||
XSPEC>help model pow | ! | Go to the help text for the powerlaw model. |
List possible lines in the specified energy range.
identify | <energy> <delta_energy> <redshift> <line_list> |
The energy range searched is <energy> < >in the rest frame of the source. <line list> specifies the list of lines to be searched. The options are bearden, which searches the Bearden compilation of fluorescence lines (Bearden, J.A., 1967, Rev.Mod.Phys. 39, 78), mekal, which uses the lines from the mekal model (q.v.) and apec, which uses the APEC (http://hea-www.harvard.edu/APEC) line list. The apec option takes an additional two arguments : the temperature of the plasma (keV) and a minimum emissivity of lines to be shown. If the command xset has been used to set APECROOT then identify uses the APECROOT value to define the new atomic physics data files. See the help on the apec model for details.
ignore | <range1> [<range2>] ... [<rangeN>] |
where <rangeI> =:: {<data set range>:<channel range> | <channel range>}. If no <data set range> is given, then the previous range is used (the initial default range is file one (1) only).<data set range> =:: {<init data set> - <last data set> | <data set>} where <init data set>, <last data set>, and <data set> are data set numbers, in the order that they were input with the data command.<channel range> =:: { <initial channel> - <last channel> | <channel>}. If integers are given for the channel ranges then channels will be used while if reals are given then energies (or wavelenths if setplot wave has been specified). If only the last channel is indicated, then a default value of one (1) is used for the initial channel. Channels remain ignored until they are explicitly noticed with the notice command, or if a data set is replaced with another data set with a different number of PHA channels. When a channel is ignored, the counts and other arrays are compressed, freeing up memory. Thus, the energy range covered by the current response matrix may be reduced.
Examples:
Assume that 4 data sets have been read in, the first 2 with 100 channels and the last 2 with 50 channels.
XSPEC>ignore :1-10 | ! | The first 10 channels of all 4 data sets are ignored. | |||
XSPEC>ignore 80- | ! | An attempt will be made to ignore channels 80 in all four data sets (as that was the last data set range specified). As a result,only channels 80-100 will be ignored for data sets 1 and 2. No change will occur for data sets 3 and 4, as they have no channels greater than 50. | |||
XSPEC>ign 4:1-20 3:30-40 45- | ! | Channels 11-20 for data set 4 are ignored (1-10 were ignored already) while channels 30-40 and 45-50 of data set 3 are ignored. | |||
XSPEC>ignore 1:1-5 | ! | No channels are ignored, as these were ignored at the beginning. | |||
XSPEC>ign 2:1.-5. | ! | Ignore all channels between 1 and 5 keV in the second dataset. |
Try to find a new minimum.
improve |
This command runs the MINUIT improve command which attempts to find a new local minimum in the vicinity of the current minimum. This gives some global minimization capability.
iplot | <plot type> |
This command works like the plot command (see the plot command description), but allows the user to change the plot and to add text to the plot interactively using the PLT package. See Appendix A and Section 4.6.
log | <STAMP> <log file> |
where <log file> is the name of the file to be opened (default
extension is .log). If no arguments are on the line, then the
default file name is xspec.log. If <log file> matches the
string none, then the current log file is
closed. If the string STAMP is given as an argument then the log
filename will include a data and time stamp. If <log file> has no
suffix then the stamp is appended to the name and a .log suffix added.
To change the chattiness level for the log file (ie. the amount of
information written to the log file) use the chatter command. The
default chatter level for the log file is 10.
Examples:
XSPEC>log | ! | Turn on the log file (default xspec.log). | |||
XSPEC>log none | ! | Close the log file. | |||
XSPEC>log mylog | ! | Open the log file ( mylog.log). | |||
XSPEC>chatter ,, 12 | ! | Set the log file chattiness to 12. |
lumin | [<lowEnergy> [<hiEnergy>] [<redshift>] |
where <low Energy> and <hi Energy> are the rest frame energies over which the luminosity is calculated and<redshift> is the source redshift. Initial default values are 2 to 10 keV for 0 redshift. The luminosity is given in units of ergs/s. The energy range redshifted to the observed 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 automatically reset 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 description). The err/noerr switch sets whether errors will be estimated on the luminosity. The error algorithm is to draw parameter values from the distribution and calculate a luminosity. <number> of sets of parameter values will be drawn. The resulting luminosities 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 luminosity error.
Examples:
The current data have significant response to data within 1 to 18 keV.
XSPEC>lumin,,,0.5 | ! | Calculate the current model luminosity over the default range for z=0.5 | |||
XSPEC>lumin 6.4 7.0 | ! | Calculate the current luminosity over 6.4 to 7 keV. |
Define a simple model using an algebraic expression.
mdefine | [<name> [<expression> [: [<type>] [<emin emax>]]] |
where <name> is the name of the model, with maximum length of 8 characters. If <name> is a previously defined model with mdefine, the current definition will overwrite the old one, and the user is warned; if it is a built-in model, however, the user will be asked to use a different name. <expression> is a string of algebraic expressions, with maximum length 512 characters. The simple rules for expressions are :
: <type> can be used to specify the type of the model. Valid types are (add, mul, mix, con). Please note that the character ``:'' must be used to separate the options from the <expression>. If <type> is not given, the default is add. Note that if type = mix, then the <expression> defines a brightness profile, and the special name e or E in the expression is taken to be the radius variable.
<emin emax> specify the minimum and maximum energy values for the model. Default values are 1.e-20 and 1.e+20, respectively.
Note that mdefine can also be used to display and delete previously defined models. The command mdefine with no arguments will display the name, type, and expression of all defined models. A single argument of a model name will display name, type, and expression just for that model. The model name followed by : will delete the specified model.
The following operators are recognized in an expression
+ | addition operator |
- | substraction operator |
* | multiplication operator |
/ | division operator |
** | (or ) exponentiation operator |
The following intrinsic functions are supported. mdefine is
case-insensitive (e.g. EXP = exp).
Unary :
EXP (expr) | = | exponential of an expression |
SIN (expr) | = | sine of vector expression in rad |
SIND (expr) | = | sine of an expression in degree |
COS (expr) | = | cosine of an expression in rad |
COSD (expr) | = | cosine of an expression in degree |
TAN (expr) | = | tangent of an expression in rad |
TAND (expr) | = | tangent of an expression in degree |
LOG (expr) | = | base 10 log of an expression |
LN (expr) | = | natural log of an expression |
SQRT (expr) | = | square root of an expression |
ABS (expr) | = | absolute value of an expression |
INT (expr) | = | integer part of an expression |
ASIN (expr) | = | arcsin of an expression in rad |
ACOS (expr) | = | arccos of an expression in rad |
MEAN (expr) | = | mean value of an expression |
DIM (expr) | = | dimension of an expression |
SMIN (expr) | = | minimum value of an expression |
SMAX (expr) | = | maximum value of an expression |
Binary :
MAX (expr1, expr2) | = | maximum of the two expressions |
MIN (expr1, expr2) | = | minimum of the two expressions |
XSPEC>mdef dplaw E**p1 + f*E**p2
! | define a model named "dplaw" with 3 parameters, p1, p2, f |
XSPEC>mdef junk a*e+b*log(e)/sin(e)
! | define a model named "junk" with 2 parameters (a, b) |
XSPEC> mdef junk2 exp(-a*e) : mul
! | define a multiplicative model with one parameter, a |
XSPEC>mdef junk3 0.2+B*e : mix | ! | define a mixing model named "junk3" with 1 parameter, B | |||
XSPEC>mdef bb E**2/T**4/(exp(E/T)-1) |
! | try to define a blackbody model with name "bb" |
Warning: "bb" is a pre-defined model. Please use a different name for your model. XSPEC> mdef sg exp(-E^2/(2*A*.E)) / sqrt(6.283*A*sqrt(.E)) : con
! | this defines a Gaussian convolution model with sigma varying with square root of energy. | ||||
! | |||||
XSPEC>mdef junk2 : | ! | delete junk2 | |||
XSPEC>mdef |
! | display all user-defined models | |||
! |
- Name - T -------- Expression ----- dplaw 1 E**p1+f*E**p2 junk 1 a*E+b*LOG(E)/SIN(E) junk3 3 a+b*E sg 4 EXP(-E^2/(2*A*.E))/SQRT(6.283*A*SQRT(.E)) ------------------------------------
Set the minimization method.
method | <algorithm> [<# of trials/evaluations> [<critical delta> [<start temperature> [<temperature reduction factor>]]]] |
where <algorithm> is the method in use and the other arguments are control values for the minimization. Their meanings are explained under the individual methods. Note that all but Lev-Marq and Anneal require the MINUIT library from CERN to be linked into XSPEC. If any of the MINUIT library methods are set then the error command will use the MINUIT MINOS command to find the confidence regions.
method anneal | [<# of eval> [<crit delta> [<start temp> [<temp reduction factor>]]]] |
An experimental global minimization method using a simulated annealing algorithm. This needs tuning to work well for X-ray data. <# of eval> is the number of function evaluations to perform before giving up, <crit delta> is the convergence criterion, <start temp> is the initial annealing temperature, and<temp reduction factor> is the fractional reduction in temperature for each cycle.
method genetic | [<# of generations> [<init|noinit>]] |
A global minimization method based on evolution by natural selection. The algorithm used is described by Charbonneau, P., 1995, ApJSuppl, 101, 309. If the init flag is set then the initial population is generated randomly from the entire allowed ranges of the fit parameters. If noinit is set then the algorithm continues from the last population generated. Note that this method is slow - tests with 3 free parameters show that thousands of generations are required to converge on the correct fit.
method leven | [<# of trials> [<crit delta>]] |
The default XSPEC minimization method using the modified Levenberg-Marquardt based on the CURFIT routine from Bevington. <# of trials> is the number of trial vectors before the user is prompted to say whether they want to continue fitting. <crit delta> is the convergence criterion.
method migrad | [<# of eval> [<crit delta>]] |
The MINUIT MIGRAD method. <# of eval> is the number of function evaluations to perform before giving up and <crit delta> is the convergence criterion.
method minim | [<# of eval> [<crit delta>]] |
The MINUIT MINIMIZE method, uses MIGRAD unless it gets into trouble in which case it switches to SIMPLEX. <# of eval> is the number of function evaluations to perform before giving up and <crit delta> is the convergence criterion.
method monte | [<# of eval> [<crit delta>]] |
The MINUIT SEEK method, a simple random sampling of parameter space (not recommended !). <# of eval> is the number of function evaluations to do before giving up and <crit delta> is the convergence criterion.
The MINUIT SIMPLEX method. <# of eval> is the number of function evaluations to perform before giving up and <crit delta> is the convergence criterion.
model | [<delimiter>] <component1> <delimiter> <component2> <delimiter> ... <componentN> [<delimiter>] |
where <delimiter> is some combination of (, +, *, ), and <componentJ> is one of the models known to XSPEC. Descriptions of these models may be accessed using the help model command. The models are divided into four types: additive, multiplicative, convolution and mixing models. Additive models are those directly associated with sources, such as power laws, thermal models, emission lines, etc. The net effect of two independent additive models is just the sum of their individual emissivities. Multiplicative models, on the other hand, do not directly produce photons, but instead modify (by an energy-dependent multiplicative parameter) the spectrum produced by one or more additive components. Examples of multiplicative models are photoelectric absorption models, edges, absorption lines, etc. Convolution models are like multiplicative models in that they modify the spectrum, but unlike multiplicative models they modify the spectrum as a whole, allowing for more complex operations than bin by bin multiplication factors. An example of a convolution model is a gaussian smoothing with energy dependent sigma. Note that when using convolution models, ordering of components may become significant. See under ``combination rules'' for a explanation of the order in which convolution and multiplicative models are applied.
Mixing models are a special case for multiple datagroups and mix the model up between the datagroups.
A list of all the currently installed models is given in response to the component ? (this will leave the current model in use). To remove the current model, type model none. See the commands delcomp, addcomp and editmod for details on how to modify the current model without having to enter a completely new model.
Model components are combined in the obvious algebraic way, with + seperating additive models, * separating multiplicative models, and parentheses to show which additive models the multiplicative models act on (syntactically, convolution and mixing models are treated as multiplicative models). The * need not be included next to parentheses, where it is redundant. Also, if only one additive model is being modified by one or more multiplicative models, the required brackets may be replaced by a *. In this case the additive model must be the last component in the grouping. Thus
is a valid model, where the M's signify multiplicative models and the A's additive models. One may also specify one additional nesting of parentheses, so that one or more overall multiplicative components are specified, along with the possiblity of having additive components outside the overall multiplicative grouping. Thus
is a valid model.
The old style syntax for entering models (versions 9.02 and earlier) is supported in version 11, but may not be supported in future versions. The following restriction applies, however: any background components must be entered on the command line as the last components in the component list.
When XSPEC parses the model syntax, it organizes the model components into additive groups, each group containing additive components and the multiplicative components which modify them. In addition there is an overall additive group, which contains the overall multiplicative components and any additve components outside the overall multiplicative grouping. Therefore, if Aij is the ith additive model in the jth group, and similarly Mij is a multiplicative model, the total spectrum is given by
Each component may have one or more parameters that can be varied during the fit (see the newpar command writeup).
When using convolution models, the order in which they are applied in the additive group can be significant. For example, the two models
are not necessarily equivalent (here the C's represent convolution models). The way XSPEC handles the ordering of components is by first computing the spectrum for the additive components of a given additive group (A1+A2 in the above example). It then applies all multiplicative or convolution components in the additive group from right to left, in the order they appear in the model formula. For example, in the model
The multiplicative and convolution components would be applied in the order M4, C3, M2, C1. Overall multiplicative and convolution components are handled similiarly. Any mixing models in an additive group are applied last, after any convolution or multiplicative models.
Examples:
Note that po and ga are additive models, and that wabs and phabs are multiplicative models.
XSPEC> mo po ! The single component po (powerlaw) is the model. XSPEC> mo po+ga XSPEC> mo (po+ga)wabs XSPEC> mo phabs(po+ga) XSPEC> mo wa(phabs(po)+ga) XSPEC> mo wa po phabs ga ! Same model using old style syntax (deprecated). XSPEC> mo wa*phabs*po XSPEC> mo (po+po)phabs ! Note that though the first and second ! components are the same form, their ! parameters are varied separately. XSPEC> mo phabs*wa(po) XSPEC> mo pha(po)+ga+po/b ! Here po is a background model.
Auto-loaded Tcl script that guesses IDs for line components in the current model.
modid | [{<delta> | conf}] |
For each gaussian or lorentzian line in the model the identify command is run. If a number is given as an argument then that is used as the delta energy for identify. If the string ``conf'' is given as the argument then the last calculated confidence regions are searched for possible line IDs. If no argument is given then ``conf'' is assumed.