error (and rerror)

Determine the confidence region for a model parameter.

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

where `<model param range>` ::= `[<modelName>:]<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 decimal point),
is the change in fit statistic used.

For response parameters (see gain command), use rerror with identical syntax except:

`<response param range>` ::= `[<sourceNum>:]<first param>-
<last param>`

The error command uses one of two algorithms. If Monte Carlo Markov Chains
are loaded (see chain command) the error range is determined by sorting
the chain values, and then taking a central percentage of the values
corresponding to the confidence level as indicated by `<delta fit statistic>`.
This is likely to be the faster of the two algorithms.

When chains are not loaded, error's algorithm is as follows:

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>`, to
within an absolute (not fractional) tolerance of `<toler>`. 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 20 trials with
a tolerance of 0.01 in fit statistic.

If a new minimum is found in the course of finding the error, the default
behavior is to abort the calculation and then automatically rerun it using
the new best fit parameters. If you prefer not to automatically rerun the
error calculation, then enter `nonew` at the start of the
command string. 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.

Since there are very many scenarios which may cause an error calculation to fail, it is highly recommended that you check the results by viewing the 9-letter error string, which is part of the output from the tclout error command (see tclout for a description of the error string). If everything went well, the error string should be “FFFFFFFFF”.

Examples:

//Assume that the current model has four model parameters. XSPEC12> error 1-4 //Estimate the 90% confidence ranges for each parameter. XSPEC12> error 9.0 //Estimate the confidence range for parameters 1-4 with delta fit // statistic = 9.0, equivalent to the 3 sigma range. XSPEC12> error 2.706 1 3 1. 2 //Estimate the 90% ranges for parameters 1 and 3, and the 1. sigma // range for parameter 2. XSPEC12> error 4 //Estimate the 1. sigma range for parameter 4. XSPEC12> error nonew 4 //Same as before, but calculation will NOT automatically restart //if a new minimum is found. XSPEC12> 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).