Skip to main content
`Ctrl`+`K`

# `fittheories`: Fit theories for `fitmanager`

This modules provides a set of fit functions and associated estimation functions in a format that can be imported into a `silx.math.fit.FitManager` instance.

These functions are well suited for fitting multiple gaussian shaped peaks typically found in spectroscopy data. The estimation functions are designed to detect how many peaks are present in the data, and provide an initial estimate for their height, their center location and their full-width at half maximum (fwhm).

The limitation of these estimation algorithms is that only gaussians having a similar fwhm can be detected by the peak search algorithm. This search fwhm can be defined by the user, if he knows the characteristics of his data, or can be automatically estimated based on the fwhm of the largest peak in the data.

The source code of this module can serve as template for defining your own fit functions.

The functions to be imported by `FitManager.loadtheories()` are defined by a dictionary `THEORY`: with the following structure:

    from silx.math.fit.fittheory import FitTheory

    THEORY = {
        'theory_name_1': FitTheory(
                            description='Description of theory 1',
                            function=fitfunction1,
                            parameters=('param name 1', 'param name 2', …),
                            estimate=estimation_function1,
                            configure=configuration_function1,
                            derivative=derivative_function1),

        'theory_name_2':  FitTheory(…),
    }

Note

The order of the provided dictionary is taken into account.

Theory names can be customized (e.g. `gauss, lorentz, splitgauss`…).

The mandatory parameters for `FitTheory` are `function` and `parameters`.

You can also define an `INIT` function that will be executed by `FitManager.loadtheories()`.

See the documentation of `silx.math.fit.fittheory.FitTheory` for more information.

## Module members:

DEFAULT_CONFIG = {'AutoFwhm': True, 'AutoScaling': False, 'DeltaPositionFwhmUnits': 0.5, 'ForcePeakPresence': True, 'FwhmPoints': 8, 'HypermetQuotedPositionFlag': True, 'HypermetTails': 15, 'InitialLongTailAreaRatio': 0.05, 'InitialLongTailSlopeRatio': 20.0, 'InitialShortTailAreaRatio': 0.05, 'InitialShortTailSlopeRatio': 0.7, 'InitialStepTailHeightRatio': 0.002, 'MaxFwhm2InputRatio': 1.5, 'MaxLongTailAreaRatio': 0.3, 'MaxLongTailSlopeRatio': 50.0, 'MaxShortTailAreaRatio': 0.1, 'MaxShortTailSlopeRatio': 2.0, 'MaxStepTailHeightRatio': 0.01, 'MinFwhm2InputRatio': 0.4, 'MinGaussArea4LongTail': 1000.0, 'MinGaussArea4ShortTail': 50000.0, 'MinGaussHeight4StepTail': 5000.0, 'MinLongTailAreaRatio': 0.01, 'MinLongTailSlopeRatio': 5.0, 'MinShortTailAreaRatio': 0.001, 'MinShortTailSlopeRatio': 0.5, 'MinStepTailHeightRatio': 0.0001, 'NoConstraintsFlag': False, 'PositiveFwhmFlag': True, 'PositiveHeightAreaFlag': True, 'QuotedEtaFlag': False, 'QuotedFwhmFlag': 0, 'QuotedPositionFlag': False, 'SameAreaRatioFlag': 1, 'SameFwhmFlag': False, 'SameSlopeRatioFlag': 1, 'Sensitivity': 2.5, 'SmoothingFlag': True, 'SmoothingWidth': 5, 'StripBackgroundFlag': True, 'StripIterations': 5000, 'StripThresholdFactor': 1.0, 'StripWidth': 2, 'Yscaling': 1.0}

  This dictionary defines default configuration parameters that have effects on fit functions and estimation functions, mainly on fit constraints. This dictionary is accessible as attribute `FitTheories.config`, which can be modified by configuration functions defined in `CONFIGURE`.

class FitTheories(config=None)

  Class wrapping functions from `silx.math.fit.functions` and providing estimate functions for all of these fit functions.

  ahypermet(x, *pars)

    Wrapping of `silx.math.fit.functions.sum_ahypermet()` without the tail flags in the function signature.

    Depending on the value of self.config[‘HypermetTails’], one can activate or deactivate the various terms of the hypermet function.

    self.config[‘HypermetTails’] must be an integer between 0 and 15. It is a set of 4 binary flags, one for activating each one of the hypermet terms: gaussian function, short tail, long tail, step.

    For example, 15 can be expressed as `1111` in base 2, so a flag of 15 means all terms are active.

  poly(x, *pars)

    Order n polynomial. The order of the polynomial is defined by the number of coefficients (`*pars`).

  static estimate_poly(x, y, n=2)

    Estimate polynomial coefficients for a degree n polynomial.

  estimate_quadratic(x, y)

    Estimate quadratic coefficients

  estimate_cubic(x, y)

    Estimate coefficients for a degree 3 polynomial

  estimate_quartic(x, y)

    Estimate coefficients for a degree 4 polynomial

  estimate_quintic(x, y)

    Estimate coefficients for a degree 5 polynomial

  strip_bg(y)

    Return the strip background of y, using parameters from `config` dictionary (StripBackgroundFlag, StripWidth, StripIterations, StripThresholdFactor)

  guess_yscaling(y)

    Estimate scaling for y prior to peak search. A smoothing filter is applied to y to estimate the noise level (chi-squared)

    Parameters:

      y – Data array

    Returns:

      Scaling factor

  peak_search(y, fwhm, sensitivity)

    Search for peaks in y array, after padding the array and multiplying its value by a scaling factor.

    Parameters:

      - y – 1-D data array

      - fwhm (int) – Typical full width at half maximum for peaks, in number of points. This parameter is used for to discriminate between true peaks and background fluctuations.

      - sensitivity (float) – Sensitivity parameter. This is a threshold factor for peak detection. Only peaks larger than the standard deviation of the noise multiplied by this sensitivity parameter are detected.

    Returns:

      List of peak indices

  estimate_height_position_fwhm(x, y)

    Estimation of Height, Position, FWHM of peaks, for gaussian-like curves.

    This functions finds how many parameters are needed, based on the number of peaks detected. Then it estimates the fit parameters with a few iterations of fitting gaussian functions.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Height, Position, FWHM. Fit constraints depend on `config`.

  estimate_agauss(x, y)

    Estimation of Area, Position, FWHM of peaks, for gaussian-like curves.

    This functions uses `estimate_height_position_fwhm()`, then converts the height parameters to area under the curve with the formula `area = sqrt(2*pi) * height * fwhm / (2 * sqrt(2 * log(2))`

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Area, Position, FWHM. Fit constraints depend on `config`.

  estimate_alorentz(x, y)

    Estimation of Area, Position, FWHM of peaks, for Lorentzian curves.

    This functions uses `estimate_height_position_fwhm()`, then converts the height parameters to area under the curve with the formula `area = height * fwhm * 0.5 * pi`

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Area, Position, FWHM. Fit constraints depend on `config`.

  estimate_splitgauss(x, y)

    Estimation of Height, Position, FWHM1, FWHM2 of peaks, for asymmetric gaussian-like curves.

    This functions uses `estimate_height_position_fwhm()`, then adds a second (identical) estimation of FWHM to the fit parameters for each peak, and the corresponding constraint.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Height, Position, FWHM1, FWHM2. Fit constraints depend on `config`.

  estimate_pvoigt(x, y)

    Estimation of Height, Position, FWHM, eta of peaks, for pseudo-Voigt curves.

    Pseudo-Voigt are a sum of a gaussian curve G(x) and a lorentzian curve L(x) with the same height, center, fwhm parameters: `y(x) = eta * G(x) + (1-eta) * L(x)`

    This functions uses `estimate_height_position_fwhm()`, then adds a constant estimation of eta (0.5) to the fit parameters for each peak, and the corresponding constraint.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Height, Position, FWHM, eta. Constraint for the eta parameter can be set to QUOTED (0.–1.) by setting `config`['QuotedEtaFlag'] to ``True``. If this is not the case, the constraint code is set to FREE.

  estimate_splitpvoigt(x, y)

    Estimation of Height, Position, FWHM1, FWHM2, eta of peaks, for asymmetric pseudo-Voigt curves.

    This functions uses `estimate_height_position_fwhm()`, then adds an identical FWHM2 parameter and a constant estimation of eta (0.5) to the fit parameters for each peak, and the corresponding constraints.

    Constraint for the eta parameter can be set to QUOTED (0.–1.) by setting `config`['QuotedEtaFlag'] to ``True``. If this is not the case, the constraint code is set to FREE.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Height, Position, FWHM1, FWHM2, eta.

  estimate_splitpvoigt2(x, y)

    Estimation of Height, Position, FWHM1, FWHM2, eta1, eta2 of peaks, for asymmetric pseudo-Voigt curves.

    This functions uses `estimate_height_position_fwhm()`, then adds an identical FWHM2 parameter and a constant estimation of eta1 and eta2 (0.5) to the fit parameters for each peak, and the corresponding constraints.

    Constraint for the eta parameter can be set to QUOTED (0.–1.) by setting `config`['QuotedEtaFlag'] to ``True``. If this is not the case, the constraint code is set to FREE.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Height, Position, FWHM1, FWHM2, eta1, eta2.

  estimate_apvoigt(x, y)

    Estimation of Area, Position, FWHM1, eta of peaks, for pseudo-Voigt curves.

    This functions uses `estimate_pvoigt()`, then converts the height parameter to area.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: Area, Position, FWHM, eta.

  estimate_ahypermet(x, y)

    Estimation of area, position, fwhm, st_area_r, st_slope_r, lt_area_r, lt_slope_r, step_height_r of peaks, for hypermet curves.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each peak are: area, position, fwhm, st_area_r, st_slope_r, lt_area_r, lt_slope_r, step_height_r .

  estimate_stepdown(x, y)

    Estimation of parameters for stepdown curves.

    The functions estimates gaussian parameters for the derivative of the data, takes the largest gaussian peak and uses its estimated parameters to define the center of the step and its fwhm. The estimated amplitude returned is simply `max(y) - min(y)`.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit newconstraints. Parameters to be estimated for each stepdown are: height, centroid, fwhm .

  estimate_slit(x, y)

    Estimation of parameters for slit curves.

    The functions estimates stepup and stepdown parameters for the largest steps, and uses them for calculating the center (middle between stepup and stepdown), the height (maximum amplitude in data), the fwhm (distance between the up- and down-step centers) and the beamfwhm (average of FWHM for up- and down-step).

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each slit are: height, position, fwhm, beamfwhm .

  estimate_stepup(x, y)

    Estimation of parameters for a single step up curve.

    The functions estimates gaussian parameters for the derivative of the data, takes the largest gaussian peak and uses its estimated parameters to define the center of the step and its fwhm. The estimated amplitude returned is simply `max(y) - min(y)`.

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints. Parameters to be estimated for each stepup are: height, centroid, fwhm .

  estimate_periodic_gauss(x, y)

    Estimation of parameters for periodic gaussian curves: number of peaks, distance between peaks, height, position of the first peak, fwhm

    The functions detects all peaks, then computes the parameters the following way:

    > - distance: average of distances between detected peaks

    > - height: average height of detected peaks

    > - fwhm: fwhm of the highest peak (in number of samples) if

    >     field `'AutoFwhm'` in `config` is `True`, else take the default value (field `'FwhmPoints'` in `config`)

    Parameters:

      - x – Array of abscissa values

      - y – Array of ordinate values (`y = f(x)`)

    Returns:

      Tuple of estimated fit parameters and fit constraints.

  configure(**kw)

    Add new / unknown keyword arguments to `config`, update entries in `config` if the parameter name is a existing key.

    Parameters:

      kw – Dictionary of keyword arguments.

    Returns:

      Configuration dictionary `config`

THEORY = {'Area Gaussians': <silx.math.fit.fittheory.FitTheory object>, 'Area Lorentz': <silx.math.fit.fittheory.FitTheory object>, 'Area Pseudo-Voigt': <silx.math.fit.fittheory.FitTheory object>, 'Atan': <silx.math.fit.fittheory.FitTheory object>, 'Degree 2 Polynomial': <silx.math.fit.fittheory.FitTheory object>, 'Degree 3 Polynomial': <silx.math.fit.fittheory.FitTheory object>, 'Degree 4 Polynomial': <silx.math.fit.fittheory.FitTheory object>, 'Degree 5 Polynomial': <silx.math.fit.fittheory.FitTheory object>, 'Gaussians': <silx.math.fit.fittheory.FitTheory object>, 'Hypermet': <silx.math.fit.fittheory.FitTheory object>, 'Lorentz': <silx.math.fit.fittheory.FitTheory object>, 'Pseudo-Voigt Line': <silx.math.fit.fittheory.FitTheory object>, 'Slit': <silx.math.fit.fittheory.FitTheory object>, 'Split Gaussian': <silx.math.fit.fittheory.FitTheory object>, 'Split Lorentz': <silx.math.fit.fittheory.FitTheory object>, 'Split Pseudo-Voigt': <silx.math.fit.fittheory.FitTheory object>, 'Split Pseudo-Voigt 2': <silx.math.fit.fittheory.FitTheory object>, 'Step Down': <silx.math.fit.fittheory.FitTheory object>, 'Step Up': <silx.math.fit.fittheory.FitTheory object>}

  Dictionary of fit theories: fit functions and their associated estimation function, parameters list, configuration function and description.