Lorentzian

Simples example

>>> from ffit.funcs.lorentzian import Lorentzian

# Call the fit method with x and y data.
>>> fit_result = Lorentzian().fit(x, y)

# The result is a FitResult object that can be unpacked.
>>> res, res_func = fit_result.res_and_func()

# The parameters can be accessed as attributes.
>> amplitude = fit_result.amplitude

# One can combine multiple calls in one line.
>>> res = Lorentzian().fit(x, y, guess=[1, 2, 3, 4]).plot(ax)

Final parameters

Lorentzian parameters.

Attributes:

Name	Type	Description
amplitude	float	The height of the peak.
gamma	float	The half-width at half-maximum.
x0	float	The position of the peak.
offset	float	The baseline offset.

Additional attributes

sigma (float): The full width at half-maximum.

Source code in ffit/funcs/lorentzian.py

class LorentzianParam(_t.Generic[_T], FuncParamClass):
    """Lorentzian parameters.

    Attributes:
        amplitude (float):
            The height of the peak.
        gamma (float):
            The half-width at half-maximum.
        x0 (float):
            The position of the peak.
        offset (float):
            The baseline offset.

    Additional attributes:
        sigma (float):
            The full width at half-maximum.
    """

    __slots__ = ("amplitude", "gamma", "x0", "offset")
    keys = ("amplitude", "gamma", "x0", "offset")
    amplitude: _T
    gamma: _T
    x0: _T
    offset: _T

    @property
    def sigma(self) -> _T:
        return self.gamma * 2  # type: ignore # pylint: disable=E1101

Lorentzian function.

\[ f(x) = A * \frac{\gamma^2}{(x-x_0)^2 + \gamma^2} + A_0 \]

f(x) = amplitude * gamma**2 / ((x - x0) ** 2 + gamma**2) + offset

In this notation, the width at half-height: \(\sigma = 2\gamma\)

Final parameters

The final parameters are given by LorentzianParam dataclass.

Source code in ffit/funcs/lorentzian.py

class Lorentzian(FitLogic[LorentzianResult]):  # type: ignore
    r"""Lorentzian function.
    ---------

    $$
    f(x) = A * \frac{\gamma^2}{(x-x_0)^2 + \gamma^2} + A_0
    $$

        f(x) = amplitude * gamma**2 / ((x - x0) ** 2 + gamma**2) + offset

    In this notation, the width at half-height: $\sigma = 2\gamma$


    Final parameters
    -----------------
    The final parameters are given by [`LorentzianParam`](../lorentzian_param/) dataclass.


    """

    _result_class: _t.Type[LorentzianResult] = LorentzianResult

    func = staticmethod(lorentzian_func)
    _guess = staticmethod(lorentzian_guess)
    normalize_res = staticmethod(normalize_res_list)

    _example_param = (5, 1, 3, 2)
    _example_x_min = 0
    _example_x_max = 6

    @_t.overload
    @classmethod
    def mask(  # type: ignore # pylint: disable=W0221
        cls,
        *,
        amplitude: float = None,  # type: ignore
        gamma: float = None,  # type: ignore
        x0: float = None,  # type: ignore
        offset: float = None,  # type: ignore
    ) -> "Lorentzian": ...

    @classmethod
    def mask(cls, **kwargs) -> "Lorentzian":
        return super().mask(**kwargs)

fit

fit(x, data, *, mask=None, guess=None, method='leastsq', maxfev=10000, **kwargs)

Fit the data using the specified fitting function.

This function returns FitResult see the documentation for more information what is possible with it.

Parameters:

Name	Type	Description	Default
x	_ARRAY	The independent variable.	required
data	_ARRAY	The dependent variable.	required
mask	Optional[Union[_ARRAY, float]]	The mask array or threshold for data filtering (optional).	None
guess	Optional[Union[_T, tuple, list]]	The initial guess for fit parameters (optional).	None
method	Literal['least_squares', 'leastsq', 'curve_fit']	The fitting method to use. Valid options are "least_squares", "leastsq", and "curve_fit" (default: "leastsq").	'leastsq'
**kwargs		Additional keyword arguments.	{}

Returns:

Name	Type	Description
FitResult	_T	The result of the fit, including the fitted parameters and the fitted function.

Raises:

Type	Description
ValueError	If an invalid fitting method is provided.

Source code in ffit/fit_logic.py

def fit(
    self,
    x: _ARRAY,
    data: _ARRAY,
    *,
    mask: _t.Optional[_t.Union[_ARRAY, float]] = None,
    guess: _t.Optional[_t.Union[_T, tuple, list]] = None,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    maxfev: int = 10000,
    **kwargs,
) -> _T:  # Tuple[_T, _t.Callable, _NDARRAY]:
    """
    Fit the data using the specified fitting function.

    This function returns [FitResult][ffit.fit_results.FitResult] see
    the documentation for more information what is possible with it.


    Args:
        x: The independent variable.
        data: The dependent variable.
        mask: The mask array or threshold for data filtering (optional).
        guess: The initial guess for fit parameters (optional).
        method: The fitting method to use. Valid options are "least_squares", "leastsq",
            and "curve_fit" (default: "leastsq").
        **kwargs: Additional keyword arguments.

    Returns:
        FitResult: The result of the fit, including the fitted parameters and the fitted function.

    Raises:
        ValueError: If an invalid fitting method is provided.

    """
    # Convert x and data to numpy arrays
    x, data = np.asarray(x), np.asarray(data)

    res, res_std = self._fit(
        x,
        data,
        mask=mask,
        guess=guess,
        method=method,
        maxfev=maxfev,
        **kwargs,
    )

    # param = self.param(*res, std=res_std)

    full_func = getattr(self, "full_func", self.__class__().func)

    # print(res)
    return self._result_class(
        res,
        lambda x: full_func(x, *res),
        std=res_std,
        x=x,
        data=data,
        stderr=res_std,
        stdfunc=lambda x: self.get_func_std()(x, *res, *res_std),
        original_func=self.func,
    )

async_fit async

async_fit(x, data, *, mask=None, guess=None, method='leastsq', maxfev=10000, **kwargs)

Asynchronously fits the model to the provided data.

Parameters:

Name	Type	Description	Default
x	_ARRAY	The independent variable data.	required
data	_ARRAY	The dependent variable data to fit.	required
mask	Optional[Union[_ARRAY, float]]	An optional mask to apply to the data. Defaults to None.	None
guess	Optional[_T]	An optional initial guess for the fitting parameters. Defaults to None.	None
**kwargs		Additional keyword arguments to pass to the fitting function.	{}

Returns:

Type	Description
_T	FitWithErrorResult[_T]: The result of the fitting process, including the fitted parameters and associated errors.

Source code in ffit/fit_logic.py

async def async_fit(
    self,
    x: _ARRAY,
    data: _ARRAY,
    *,
    mask: _t.Optional[_t.Union[_ARRAY, float]] = None,
    guess: _t.Optional[_T] = None,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    maxfev: int = 10000,
    **kwargs,
) -> _T:
    """
    Asynchronously fits the model to the provided data.

    Args:
        x (_ARRAY): The independent variable data.
        data (_ARRAY): The dependent variable data to fit.
        mask (Optional[Union[_ARRAY, float]], optional): An optional mask to apply to the data. Defaults to None.
        guess (Optional[_T], optional): An optional initial guess for the fitting parameters. Defaults to None.
        **kwargs: Additional keyword arguments to pass to the fitting function.

    Returns:
        FitWithErrorResult[_T]:
            The result of the fitting process, including the fitted parameters and associated errors.
    """
    return self.fit(x, data, mask=mask, guess=guess, method=method, maxfev=maxfev, **kwargs)

guess classmethod

guess(x, data, mask=None, guess=None, **kwargs)

Guess the initial fit parameters.

This function returns an object of the class FitResult. See its documentation for more information on what is possible with it.

Parameters:

Name	Type	Description	Default
x		The independent variable.	required
data		The dependent variable.	required
mask	Optional[Union[_ARRAY, float]]	The mask array or threshold for data filtering (optional).	None
guess	Optional[_T]	The initial guess for the fit parameters (optional).	None
**kwargs		Additional keyword arguments.	{}

Returns:

Name	Type	Description
FitResult	_T	The guess, including the guess parameters and the function based on the guess.

Examples:

>>> x = [1, 2, 3, 4, 5]
>>> data = [2, 4, 6, 8, 10]
>>> fit_guess = FitLogic.guess(x, data)
>>> fit_guess.plot()

Source code in ffit/fit_logic.py

@classmethod
def guess(
    cls,
    x,
    data,
    mask: _t.Optional[_t.Union[_ARRAY, float]] = None,
    guess: _t.Optional[_T] = None,
    **kwargs,
) -> _T:
    """Guess the initial fit parameters.

    This function returns an object of the class `FitResult`.
    See its documentation for more information on what is possible with it.

    Args:
        x: The independent variable.
        data: The dependent variable.
        mask: The mask array or threshold for data filtering (optional).
        guess: The initial guess for the fit parameters (optional).
        **kwargs: Additional keyword arguments.

    Returns:
        FitResult: The guess, including the guess parameters and the function based on the guess.

    Examples:
        >>> x = [1, 2, 3, 4, 5]
        >>> data = [2, 4, 6, 8, 10]
        >>> fit_guess = FitLogic.guess(x, data)
        >>> fit_guess.plot()
    """
    if guess is not None:
        return cls._result_class(
            np.asarray(guess),
            lambda x: cls.func(x, *guess),
            x=x,
            data=data,
        )
    x_masked, data_masked = get_masked_data(x, data, mask, mask_min_len=1)
    guess_param = cls._guess(x_masked, data_masked, **kwargs)
    return cls._result_class(
        np.asarray(guess_param),
        lambda x: cls.func(x, *guess_param),
        x=x,
        data=data,
    )

bootstrapping

bootstrapping(x, data, mask=None, guess=None, method='leastsq', num_of_permutations=None, **kwargs)

Fit the data using the specified fitting function.

This function returns FitResult see the documentation for more information what is possible with it.

Parameters:

Name	Type	Description	Default
x	_ARRAY	The independent variable.	required
data	_ARRAY	The dependent variable.	required
mask	Optional[Union[_ARRAY, float]]	The mask array or threshold for data filtering (optional).	None
guess	Optional[Union[_T, tuple, list]]	The initial guess for fit parameters (optional).	None
method	Literal['least_squares', 'leastsq', 'curve_fit']	The fitting method to use. Valid options are "least_squares", "leastsq", and "curve_fit" (default: "leastsq").	'leastsq'
**kwargs		Additional keyword arguments.	{}

Returns:

Name	Type	Description
FitResult	_T	The result of the fit, including the fitted parameters and the fitted function.

Raises:

Type	Description
ValueError	If an invalid fitting method is provided.

Source code in ffit/fit_logic.py

def bootstrapping(
    self,
    x: _ARRAY,
    data: _ARRAY,
    mask: _t.Optional[_t.Union[_ARRAY, float]] = None,
    guess: _t.Optional[_t.Union[_T, tuple, list]] = None,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    num_of_permutations: _t.Optional[int] = None,
    **kwargs,
) -> _T:  # Tuple[_T, _t.Callable, _NDARRAY]:
    """
    Fit the data using the specified fitting function.

    This function returns [FitResult][ffit.fit_results.FitResult] see
    the documentation for more information what is possible with it.

    Args:
        x: The independent variable.
        data: The dependent variable.
        mask: The mask array or threshold for data filtering (optional).
        guess: The initial guess for fit parameters (optional).
        method: The fitting method to use. Valid options are "least_squares", "leastsq",
            and "curve_fit" (default: "leastsq").
        **kwargs: Additional keyword arguments.

    Returns:
        FitResult: The result of the fit, including the fitted parameters and the fitted function.

    Raises:
        ValueError: If an invalid fitting method is provided.

    """
    # Convert x and data to numpy arrays
    x, data = np.asarray(x), np.asarray(data)

    # Mask the data and check that length of masked data is greater than lens of params
    x_masked, data_masked = get_masked_data(x, data, mask, self._param_len)
    if len(x_masked) == 0 or len(data_masked) == 0:
        return self._result_class(
            np.ones(self._param_len) * np.nan,
            x=x,
            data=data,
        )

    # Get a guess if not provided
    if guess is None:
        guess = self._guess(x_masked, np.mean(data_masked, axis=0), **kwargs)

    # Fit ones to get the best initial guess
    guess, cov = self._run_fit(x_masked, np.mean(data_masked, axis=0), guess, method)

    # Run fit on random subarrays
    all_res = []
    for xx, yy in get_random_array_permutations(x_masked, data_masked, num_of_permutations):
        res, _ = self._run_fit(xx, yy, guess, method)
        if self.normalize_res is not None:  # type: ignore
            res = self.normalize_res(res)  # type: ignore
        all_res.append(res)

    res_means = np.mean(all_res, axis=0)
    bootstrap_std = np.std(all_res, axis=0)
    # total_std = np.sqrt(np.diag(cov) + bootstrap_std**2)
    total_std = bootstrap_std

    full_func = getattr(self, "full_func", self.__class__().func)

    return self._result_class(
        res_means,
        lambda x: full_func(x, *res_means),
        x=x,
        data=data,
        cov=cov,  # type: ignore
        stderr=total_std,  # type: ignore
        stdfunc=lambda x: self.get_func_std()(x, *res_means, *total_std),
        original_func=self.func,
    )

bootstrapping2D

bootstrapping2D(x, data, mask=None, guess=None, method='leastsq', num_of_permutations=None, **kwargs)

Fit the data using the specified fitting function.

This function returns FitResult see the documentation for more information what is possible with it.

Parameters:

Name	Type	Description	Default
x	_ARRAY	The independent variable.	required
data	_2DARRAY	The 2D dependent variable (data, batches).	required
mask	Optional[Union[_ARRAY, float]]	The mask array or threshold for data filtering (optional).	None
guess	Optional[Union[_T, tuple, list]]	The initial guess for fit parameters (optional).	None
method	Literal['least_squares', 'leastsq', 'curve_fit']	The fitting method to use. Valid options are "least_squares", "leastsq", and "curve_fit" (default: "leastsq").	'leastsq'
**kwargs		Additional keyword arguments.	{}

Returns:

Name	Type	Description
FitResult	_T	The result of the fit, including the fitted parameters and the fitted function.

Raises:

Type	Description
ValueError	If an invalid fitting method is provided.

Source code in ffit/fit_logic.py

def bootstrapping2D(
    self,
    x: _ARRAY,
    data: _2DARRAY,
    mask: _t.Optional[_t.Union[_ARRAY, float]] = None,
    guess: _t.Optional[_t.Union[_T, tuple, list]] = None,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    num_of_permutations: _t.Optional[int] = None,
    **kwargs,
) -> _T:  # Tuple[_T, _t.Callable, _NDARRAY]:
    """
    Fit the data using the specified fitting function.

    This function returns [FitResult][ffit.fit_results.FitResult] see
    the documentation for more information what is possible with it.

    Args:
        x: The independent variable.
        data: The 2D dependent variable (data, batches).
        mask: The mask array or threshold for data filtering (optional).
        guess: The initial guess for fit parameters (optional).
        method: The fitting method to use. Valid options are "least_squares", "leastsq",
            and "curve_fit" (default: "leastsq").
        **kwargs: Additional keyword arguments.

    Returns:
        FitResult: The result of the fit, including the fitted parameters and the fitted function.

    Raises:
        ValueError: If an invalid fitting method is provided.

    """
    # Convert x and data to numpy arrays
    x, data = np.asarray(x), np.asarray(data)

    # Mask the data and check that length of masked data is greater than lens of params
    x_masked, data_masked = get_masked_data(x, data, mask, self._param_len)
    if len(x_masked) == 0 or len(data_masked) == 0:
        return self._result_class(
            np.ones(self._param_len) * np.nan,
            x=x,
            data=data,
        )

    # Get a guess if not provided
    if guess is None:
        guess = self._guess(x_masked, np.mean(data_masked, axis=-1), **kwargs)

    # Fit ones to get the best initial guess
    guess, cov = self._run_fit(x_masked, np.mean(data_masked, axis=-1), guess, method)

    # Run fit on random subarrays
    all_res = []
    total_elements = data_masked.shape[1]
    if num_of_permutations is None:
        num_of_permutations = int(min(max(total_elements / 10, 1_000), 5_000))

    for selected_index in bootstrap_generator(total_elements, num_of_permutations):
        res, _ = self._run_fit(
            x_masked, np.mean(data_masked[:, selected_index], axis=-1), guess, method
        )
        if self.normalize_res is not None:  # type: ignore
            res = self.normalize_res(res)  # type: ignore
        all_res.append(res)

    res_means = np.mean(all_res, axis=0)
    bootstrap_std = np.std(all_res, axis=0)
    total_std = bootstrap_std

    full_func = getattr(self, "full_func", self.__class__().func)

    return self._result_class(
        res_means,
        lambda x: full_func(x, *res_means),
        x=x,
        data=data,
        cov=cov,  # type: ignore
        stderr=total_std,  # type: ignore
        stdfunc=lambda x: self.get_func_std()(x, *res_means, *total_std),
        original_func=self.func,
    )