FitManager

class xspec.FitManager

Xspec fitting class.

PyXspec automatically creates a single object of this class, named Fit.

Methods

  • compare

  • error

  • ftest

  • globalFit

  • goodness

  • improve

  • perform

  • renorm

  • show

  • simulate

  • steppar

  • stepparResults

Attributes ((*) = get-only)

  • bayes

  • bayesPriors

  • covariance*

  • criticalDelta

  • delta

  • dof*

  • globalBasins*

  • method

  • nIterations

  • nullhyp*

  • nVarPars*

  • previousGoodness*

  • previousGoodnessSims*

  • query

  • useChainRule

  • statMethod

  • statTest

  • statistic*

  • testStatistic*

  • weight

__init__()
compare(alternatives, method='lm', useGlobal=False)

Compare alternative models against the current model (model selection).

Evaluates each alternative model against the current data, ignore ranges and statistic -- carrying shared parameters over by name from the current best fit -- and returns a per-model table. The current model is included as a baseline row, and the original model is restored afterwards (compare is non-destructive). The interactive compare table is also printed.

Args:
alternatives: a model-expression string, or a list of them

(e.g. "tbabs*powerlaw" or ["phabs*powerlaw", "tbabs*bbody"]). An entry of the form "@file.xcm" is a candidate defined by a previously-saved model file (sourced for its own model AND priors -- the way to give a comparison model custom priors for the 'nest' method).

method: how each alternative is evaluated [str]:

'lm' -- fit with the current fit method (default);

'global' -- fit with fit global (Differential Evolution) so a

stuck local minimum cannot corrupt its AIC/BIC;

'nest' -- nested sampling, ranking by Bayesian evidence

(ln Z) instead of AIC/BIC. Each parameter's prior comes from the current model (carried by name) unless overridden by an @file.xcm candidate; a parameter with no explicit bayes <par> <prior> is sampled from a uniform (CONS) prior over its limits. Refuses to run if any parameter would be sampled under a CONS prior spanning >4 decades.

useGlobal: deprecated alias for method='global' [bool].

Returns a list of dicts, one per model. Always present: 'model', 'current' (bool), 'ok' (bool), 'statistic', 'dof', 'nPars', 'aic', 'bic', 'deltaStat', 'deltaAIC', 'deltaBIC', 'params' (a {name: (value, sigma)} dict of shared parameters). For method='nest' the ranking is by Bayesian evidence, so 'statistic', 'dof', 'aic', 'bic' and the three delta* fields are None ('nPars' stays the free- parameter count); each dict instead carries 'logZ', 'logZerr', 'deltaLogZ' (<=0, vs the best model) and 'postProb' (posterior model probability under equal model priors), and 'hasEvidence' is True. For 'lm'/'global', deltaAIC / deltaBIC are relative to the best row; a negative deltaAIC/deltaBIC flags a model an information criterion prefers despite a worse fit.

Note

AIC/BIC differences are meaningful only under a fixed statistic and identical noticed data; an alternative that changes the noticed-channel count is skipped.

error(argString, respPar=False)

Determine confidence intervals of a fit.

Args:
argString:

A string with identical syntax to the standard interactive XSPEC error command.

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

where <model param range> ::=[<modelName>:]<first param> -

<last param>

See the XSPEC manual for a more detailed description.

respPar: Optional flag. Set this to True if the parameters

are response parameters. [bool]

The results of the error command are stored in the error attributes of the individual Parameter objects.

Examples:

# Estimate the 90% confidence ranges for parameters 1-3
Fit.error("1-3")
# Repeat but with delta fit statistic = 9.0, equivalent to the
# 3 sigma range.
Fit.error("9.0")
# Estimate for parameter 3 after setting the number of trials to 20.
# Note that the tolerance field has to be included (or skipped over).
Fit.error("stop 20,,3")
# Perform an error calculation on response parameter 1
Fit.error("1",True)
ftest(chisq2, dof2, chisq1, dof1)

Calculate the F-statistic and its probability given new and old values of chisq and number of degrees of freedom (DOF).

Args:

chisq2: [float]

dof2: [int]

chisq1: [float]

dof1: [int]

chisq2 and dof2 should come from a new fit, in which an extra model component was added to (or a frozen parameter thawed from) 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 2002, ApJ 571, 545).

Returns: The F-test probability [float].

globalFit(maxGen=None, popSize=None)

Perform a global fit (cold-start Differential Evolution + polish).

Runs a derivative-free Differential Evolution search over the soft limits of the thawed parameters to escape local minima, then polishes the global best with the currently selected Fit.method (so the final statistic, covariance and errors are identical to a normal fit under that method). Never regresses on the prior fit.

Args:

maxGen: Optional max number of DE generations [int].

popSize: Optional DE population size [int]. Because the

underlying fit global arguments are positional, popSize may only be given together with maxGen.

Competitive degenerate minima found during the search are stored in Fit.globalBasins. This is the Python face of the interactive fit global [maxGen [popSize]] command.

goodness(nRealizations=100, sim=False, fit='fit')

Perform a Monte Carlo calculation of the goodness-of-fit.

Args:

nRealizations: Number of spectra to simulate [int].

sim: flag [bool]

If False (default), all simulations are drawn from the best fit model parameter values. If True, parameters will be drawn from a Gaussian centered on the best fit.

fit: switch indicating fitting will be performed [string]

Only "fit" and "nofit" are accepted. Default is "fit" (fitting will be performed).

improve()

Try to escape the current minimum (warm-restart global search).

Runs a Differential Evolution pass seeded in a shell about the current best fit, then polishes the result with the currently selected Fit.method (Levenberg-Marquardt or a MINUIT algorithm). This is the warm-restart counterpart of Fit.globalFit(): it works for every method, and never regresses (if it cannot beat the prior fit, the original parameters are restored). Any competitive basins found are available in Fit.globalBasins.

perform()

Perform a fit.

renorm(setting=None)

Renormalize the model to minimize statistic with current parameters.

Args:

setting: [string]

If None, this will perform an explicit immediate renormalization. Other options determine when renormalization will be performed automatically. They are the following strings:

  • 'auto': Renormalize after a model command or parameter change, and at the beginning of a fit.

  • 'prefit': Renormalize only at the beginning of a fit.

  • 'none': Perform no automatic renormalizations.

show()

Show fit information.

simulate(nRealizations, fSigma=1.0, nostat=False, fit=False, hook=None)

Bulk posterior-predictive simulation (the sim command).

Draw nRealizations parameter sets, realize the loaded spectra in place (backgrounds included), optionally refit each, and -- when a hook callable is supplied -- run it after every realization and harvest its returned numbers. The loaded data, model parameters and fit state are restored on return.

Args:

nRealizations: number of realizations to draw [int > 0].

fSigma: covariance scaling for the parameter draws [float].

fSigma=0 selects fixed-parameter mode (no draws; only the counting noise varies). Ignored when parameters are drawn from loaded chains.

nostat: if True, realize the exact expected counts with no

counting (Poisson/Gaussian) noise [bool].

fit: if True, refit each realization (parametric bootstrap);

the refit parameters and statistic are returned in 'fitPars'/'fitStat' [bool].

hook: an optional callable invoked once per realization as

hook(iteration), where iteration is the 1-based, globally-unique realization index. It must return a sequence of numbers (stored as that realization's row in 'result') or None. A raised exception aborts the whole run. Simulation is serial whenever a hook is given (a forked walker cannot call back into Python).

Returns a dict with (all values are lists, numpy-friendly):

'paramIDs' : (modelName, parName, index) per drawn parameter 'drawnPars': nRealizations rows of drawn values ([] if fixed) 'stat' : the statistic of each realization 'fitPars' : refit parameters per realization ([] unless fit) 'fitStat' : refit statistic per realization ([] unless fit) 'result' : the hook's harvested rows ([] if no hook)

steppar(argString)

Perform a steppar run.

Generate the statistic "surface" for 1 or more parameters.

Args:

argString: [string]

This uses identical syntax to the standard interactive XSPEC steppar command. "<step spec> [<step spec> ...]" where:

<step spec> ::= [<log|nolog>] [<current|best>]

[<modName>:]<param index> <low value> <high value> <# steps>

See the XSPEC manual for a more detailed description of specs.

Examples:

# Step parameter 3 from 1.5 to 2.5 in 10 linear steps
Fit.steppar("3 1.5 2.5 10")
# Repeat the above but with logarithmic steps
Fit.steppar("log")
# Step parameter 2 linearly from -.2 to .2 in steps of .02
Fit.steppar("nolog 2 -.2 .2 20")
stepparResults(arg)

Retrieve values from the most recent steppar run.

Args:

arg:

argument should be 'statistic', 'delstat', 'minima', or a parameter specifier. A parameter specifier should be a string of the form:

'[<modName>:]<parNum>'

or simply an integer <parNum>.

For 'statistic', 'delstat', or a parameter specifier this returns a list of floats. For 'minima' (the grid-resolution local minima of the steppar surface, a degeneracy-discovery aid) it returns a list of (deltaStat, [paramValue, ...]) tuples ordered best-first, where the parameter values are in stepped-parameter order. The list is empty for a unimodal surface that has no interior local minimum.

property bayes

Turn Bayesian inference on or off [string].

Valid settings are 'on', 'off' (default), 'cons', 'smooth'. 'cons' turns Bayesian inference on AND gives ALL parameters a constant prior. Priors can be set for parameters individually through the Parameter object's prior attribute.

property bayesPriors

The current Bayesian prior settings, as a listing [string] (GET only).

Lists every non-constant per-parameter prior and every joint prior term (such as the projct smoothness prior set with 'bayes smooth'), in the same form 'show bayes' prints.

property covariance

The covariance matrix from the most recent fit [tuple of floats] (GET only).

As with standard XSPEC's "tclout covar", this only returns the diagonal and below-diagonal matrix elements.

property criticalDelta

Critical delta for fit statistic convergence [float].

The absolute change in the fit statistic between iterations, less than which the fit is deemed to have converged.

property delta

Set fit delta values to be proportional to the parameter value [float].

Get:

Returns the current proportional setting, or 0.0 if currently using the fixed fit delta values.

Set:

Enter the constant factor which will multiply the parameter value to produce a fit delta. A constant factor of 0.0 or negative will turn off the use of proportional fit deltas.

property dof

The degrees of freedom for the fit [int] (GET only).

property globalBasins

Competitive basins from the most recent Fit.globalFit() or Fit.improve() run [list] (GET only).

Each entry is a (stat, deltaStat, params) tuple, where params is the list of variable-parameter values (in fit order) at that basin's local minimum. Element 0 is the global best (deltaStat 0.0); any further entries are distinct minima within the competitive-basin band (delta-stat < ~9). Empty if no global search has run, or the last one did not improve on the prior fit.

Example:

Fit.globalFit()
for stat, dStat, pars in Fit.globalBasins:
    print(stat, dStat, pars)
property method

The fitting algorithm to use [string].

Choices are: 'leven', 'migrad', 'simplex'. The default is 'leven'.

When setting the method, additional arguments for <nFitIterations> and <fit critical delta> may also be entered. Valid formats for entering multiple arguments are:

# Single string
Fit.method = "migrad  100 .05"
# List of strings
Fit.method = ["migrad","100",".05"]
# List of strings and numbers
Fit.method = ["migrad", 100, .05]
property nIterations

The maximum number of fit iterations prior to query [int].

property nVarPars

The number of variable parameters for the fit [int] (GET only).

property nullhyp

The null hypothesis probability for the chi-sq fit (GET only).

property previousGoodness

The goodness value from the immediately previous call [float] (GET only).

property previousGoodnessSims

The array of simulation values from the immediately previous goodness calculation [list] (GET only).

property query

The fit query setting [string].

  • 'yes': Fit will continue through query.

  • 'no' : Fit will end at query.

  • 'on' : User will be prompted for "y/n" response.

property statMethod

The type of fit statistic in use [string].

Valid names: 'chi' | 'cstat' | 'lstat' | 'pgstat' | 'pstat' | 'whittle'. To set for individual spectra, add a spectrum number (or range) to the string: ie.

>>> Fit.statMethod = "cstat 2"
property statTest

The type of test statistic in use [string].

Valid names: 'ad' | 'chi' | 'cvm' | 'ks' | 'pchi' | 'runs'. To set for individual spectra, add a spectrum number (or range) to the string: ie.

>>> Fit.statTest = "ad 2"
property statistic

Fit statistic value from the most recent fit [float] (GET only).

This returns the total fit statistic. An individual spectrum's contribution to the total is stored in the Spectrum object's statistic attribute.

property testStatistic

Test statistic value from the most recent fit [float] (GET only).

property useChainRule

The fit useChainRule setting [string].

  • 'yes' or 'on': Fast second derivative calculation using chain rule.

  • 'no' or 'off': Slow second derivative calculation.

property weight

Change the weighting function used in the calculation of chi-sq [string].

Available functions: 'standard', 'gehrels', 'churazov', 'model'