scippneutron.peaks.fit_peaks

scippneutron.peaks.fit_peaks(data, *, peak_estimates, windows, background, peak, fit_parameters=None, fit_requirements=None)

Fit peaks to data.

This function fits peaks to 1-dimensional data. The number of peaks and their approximate locations are determined by peak_estimates.

When defining fit windows, it is important that every window contains only one peak. Otherwise, fits may fail or converge to the wrong peak. Windows are, however, allowed to overlap as long as that overlap does not contain the bulk of a peak.

Consider adjusting windows and fit_parameters if fits fail with all models. Only change fit_requirements if really needed as this may lead to bad fits being marked as succeeded.

Fit procedure

For each peak, initial model parameters are estimated using model.Model.guess() with the data within the fit window. Then, two fits are performed, one with only the background and one with background + peak using scipp.scipy.optimize.curve_fit().

If the latter fit converges, it is assessed based on several criteria like FitRequirements.min_p_value and the width of the obtained peak. In addition, the combined background + peak model must yield a better fit than the background alone (determined by their respective Akaike Information Criterion, see FitResult.aic). If the assessment fails, another set of models may be tried, see the section on model selection below.

Finally, a FitResult is constructed for each peak which contains the outcome of the assessment, the best parameters and models, and some goodness of fit statistics. Fits for each peak can succeed or fail independently.

Model selection

In the simplest case, the models for peaks and the background are given as a concrete model each, see scippneutron.peaks.model. Alternatively, they can be specified as strings. See the type annotations of the peak and background arguments for the lists of supported model names.

If it is unclear which models are best in a given case or the best model varies between peaks, peak and background can be given as iterables of models or model names. In this case, the fit is attempted with each combination of peak and background model until a fit is successful. The background is varied first.

For example, in

fit_peaks(
    background=['linear', 'quadratic'],
    peak=['gaussian', 'lorentzian'],
    ...
)

models are tried in the order

1. linear + gaussian

2. quadratic + gaussian

3. linear + lorentzian

4. quadratic + lorentzian

until the first successful fit.

Parameters:

• data (DataArray) – A 1d data array where data.data is the dependent variable and data.coords[data.dim] is the independent variable for the fit. Must be 1-dimensional and not binned.

• peak_estimates (Variable) – Initial estimates of peak locations. A peak will be fitted for each estimate. Must be a 1d variable with dimension data.dim.

• windows (Variable) –

  If a scalar, the size of fit windows. A window is constructed for each peak estimate centered on the estimate with a width equal to windows (adjusted to the data range and to maintain a separation between peaks, see FitParameters.neighbor_separation_factor).

  If a 2d array, the windows for each peak. Must have sizes {data.dim: len(data), 'range': 2} where windows['range', 0] and windows['range', 1] are the lower and upper bounds of the fit windows, respectively. The windows are not adjusted automatically in this case.

• background (Union[Model, Literal['linear', 'quadratic'], Iterable[Model], Iterable[Literal['linear', 'quadratic']]]) – The background model or models.

• peak (Union[Model, Literal['gaussian', 'lorentzian', 'pseudo_voigt'], Iterable[Model], Iterable[Literal['gaussian', 'lorentzian', 'pseudo_voigt']]]) – The peak model or models.

• fit_parameters (Optional[FitParameters], default: None) – Parameters for the fit not otherwise listed as function arguments.

• fit_requirements (Optional[FitRequirements], default: None) – Constraints on the fit result.

Returns:

list[FitResult] – A FitResult for each peak.