XSPEC Commands G-M

  
gain

Modify a response file gain, in a particularly simple way. $\ast$CAUTION$\ast$ This command is to be used with extreme care for investigation of the response properties. To properly fit data, the response matrix should be recalculated explicitly (outside of XSPEC) using any modified gain information derived. The 3 variants of this command are:

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.

algorithm

The gain command shifts the energies on which the response matrix is defined and shifts the effective area curve to match. The effective area curve stored by XSPEC is either the ARF, if one was in use, or is calculated from the RSP file as the total area in each energy range. This means that if there are sharp features in the response then these will only be handled correctly by the gain command if they are in the ARF or if no ARF is input. The new energy is calculated by E/<slope> - <intercept>.

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

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.

  
goodness

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.

  
hardcopy

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

Obtain help on the XSPEC commands, their syntax, and examples of their use.

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.

  
identify

List possible lines in the specified energy range.

identify

<energy> <delta_energy> <redshift> <line_list>

The energy range searched is <energy> $\pm$ < $\Delta_{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

Ignore data channels. (See also notice.)

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 $\ast$$\ast$:1-10			!		The first 10 channels of all 4 data sets are ignored.
XSPEC>ignore 80-$\ast$$\ast$			!		An attempt will be made to ignore channels $\geq$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-$\ast$$\ast$			!		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.

  
improve

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

Interactive plotting on the current plot device.

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

Open a log file.

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

Calculate the luminosity of the current model for a given redshift and rest frame energy range.

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.

  
mdefine

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 :

1.

The energy term, or the radius term for mixing model, must be 'e' or 'E' in the expression. Other words, which are not numerical constants nor internal functions, are assumed to be model parameters.

2.

If a convolution model varies with the location on the spectrum to be convolved, the special variable .e or .E may be used to refer to the convolution point.

3.

The maximum number of model parameters is 10.

4.

The expression may contain spaces for better readability.

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

Operators

The following operators are recognized in an expression

+	addition operator
-	substraction operator
*	multiplication operator
/	division operator
**	(or  ) exponentiation operator

Functions

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

Examples

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))
------------------------------------

  
method

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.

anneal

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.

genetic

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.

leven

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.

migrad

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.

minim

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.

monte

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.

simplex

XSPEC>method simplex [<# of eval> [<crit delta>]]

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

Define the form of the theoretical model to be fit to the data.

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.

Combination Rules

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

M1*(A1+A2) + M2*M3(A3) + M4*A4 + A5

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

M0( M1*(A1+A2) + M2*M3(A3) + A4 ) + A5

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

M10*M20*... * ( [(A11+A21+...)*M11*M21*...] + [(A12+A22+...)*...] + ... ) + A10 + A20 + ...

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

C1*M1(A1+A2)

M1*C1(A1+A2)

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

C1*M2(A1+A2)C3*M4

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.

Background Models

A component can be specified as a background model by appending the string /b to the component name. A background model is convolved with the instrumental redistribution matrix but not with the effective area. This provides a means for including a description of detector-instrumental and particle backgrounds. If a response (RMF) matrix but not an auxiliary (ARF) file has been input, then the effective-area curve is calculated by assuming that the rows of the RMF sum to one. This will lead to errors at the top and bottom of the energy range of the detector.

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.

  
modid

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.