fit

sherpa.astro.ui.fit(id: IdType | None = None, *otherids: IdType, **kwargs) → None

Fit a model to one or more data sets.

Use forward fitting to find the best-fit model to one or more data sets, given the chosen statistic and optimization method. The fit proceeds until the results converge or the number of iterations exceeds the maximum value (these values can be changed with set_method_opt). An iterative scheme can be added using set_iter_method to try and improve the fit. The final fit results are displayed to the screen and can be retrieved with get_fit_results.

Changed in version 4.17.0: The outfile parameter can now be sent a Path object or a file handle instead of a string.

Changed in version 4.17.1: The parameter record_steps was added to keep parameter values of each iteration with the fit results.

Parameters:

  • id (int or str, optional) – The data set that provides the data. If not given then all data sets with an associated model are fit simultaneously.

  • *otherids (sequence of int or str, optional) – Other data sets to use in the calculation.

  • outfile (str, Path, IO object, or None, optional) – If set, then the fit results will be written to a file with this name. The file contains the per-iteration fit results.

  • clobber (bool, optional) – This flag controls whether an existing file can be overwritten (True) or if it raises an exception (False, the default setting). This is only used if outfile is set to a string or Path object.

  • record_steps (bool, optional) – If True, then the parameter values and statistic value are recorded at each iteration in an array in the FitResults object that you can obtain with get_fit_results.

Raises:

sherpa.utils.err.FitErr – If filename already exists and clobber is False.

See also

conf

Estimate the confidence intervals using the confidence method.

contour_fit

Contour the fit to a data set.

covar

Estimate the confidence intervals using the confidence method.

fit_bkg

Fit a model to one or more background PHA data sets.

freeze

Fix model parameters so they are not changed by a fit.

get_fit_results

Return the results of the last fit.

plot_fit

Plot the fit results (data, model) for a data set.

image_fit

Display the data, model, and residuals for a data set in the image viewer.

set_stat

Set the statistical method.

set_method

Change the optimization method.

set_method_opt

Change an option of the current optimization method.

set_bkg_full_model

Define the convolved background model expression for a PHA data set.

set_bkg_model

Set the background model expression for a PHA data set.

set_full_model

Define the convolved model expression for a data set.

set_iter_method

Set the iterative-fitting scheme used in the fit.

set_model

Set the model expression for a data set.

show_fit

Summarize the fit results.

thaw

Allow model parameters to be varied during a fit.

Notes

For PHA data sets with background components, the function will fit any background components for which a background model has been created (rather than being subtracted). The fit_bkg function can be used to fit models to just the background data.

The screen output from the fit can be controlled with the SherpaVerbosity context manager, as shown in the examples.

If outfile is sent a file handle then it is not closed by this routine.

Examples

Simultaneously fit all data sets with models and then store the results in the variable fres:

>>> fit()
>>> fres = get_fit_results()

Fit just the data set ‘img’:

>>> fit('img')

Simultaneously fit data sets 1, 2, and 3:

>>> fit(1, 2, 3)

Fit the dataset ‘jet’ and keep the values for each parameter in every optimization step:

>>> fit('jet', record_steps=True)
>>> fres = get_fit_results()
>>> for row in fres.record_steps:
...     print(f"{row['nfev']} {row['statistic']:8.6e} {row['const1d.c0']:6.4f}")
[... output here ...]

(This example assumes that the model for the data set ‘jet’ has a parameter called ‘const1d.c0’.)

Fit data set ‘jet’ and write the fit results to the text file ‘jet.fit’, over-writing it if it already exists:

>>> fit('jet', outfile='jet.fit', clobber=True)

Store the per-iteration values in a StringIO object and extract the data into the variable txt (this avoids the need to create a file):

>>> from io import StringIO
>>> out = StringIO()
>>> fit(outfile=out)
>>> txt = out.getvalue()

The messages from fit use the standard Sherpa logging infrastructure, and so can be ignored by using SherpaVerbosity:

>>> from sherpa.utils.logging import SherpaVerbosity
>>> with SherpaVerbosity("WARN"):
...     fit()
...
>>> fres = get_fit_results()