Exp

Simples example

>>> from ffit.funcs.exp import Exp

# Call the fit method with x and y data.
>>> fit_result = Exp().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 = Exp().fit(x, y, guess=[1, 2, 3, 4]).plot(ax)

Final parameters

Exponential function parameters.

Attributes:

Name	Type	Description
amplitude	float	The amplitude of the exponential function.
rate	float	The rate of the exponential function.
offset	float	The offset of the exponential function.

Additional attributes

tau (float): The time constant of the exponential function, calculated as -1 / rate.

Source code in ffit/funcs/exp.py

class ExpParam(_t.Generic[_T], FuncParamClass):
    """Exponential function parameters.

    Attributes:
        amplitude (float):
            The amplitude of the exponential function.
        rate (float):
            The rate of the exponential function.
        offset (float):
            The offset of the exponential function.

    Additional attributes:
        tau (float):
            The time constant of the exponential function, calculated as -1 / rate.
    """

    keys = ("amplitude", "rate", "offset")

    amplitude: _T
    rate: _T
    offset: _T

    __latex_repr__ = r"$&amplitude \cdot \exp(&rate \cdot x) + &offset$"
    __latex_repr_symbols__ = {
        "amplitude": r"A",
        "rate": r"\Gamma",
        "offset": r"b",
    }

    @property
    def tau(self) -> _T:
        return -1 / self.rate  # type: ignore # pylint: disable=E1101

Exp function.

Function

\[ f(x) = A \exp(Γ⋅x) + A_{\text{offset}} \]

f(x) = amplitude * np.exp(rate * x) + offset

Final parameters

The final parameters are given by ExpParam dataclass.

Source code in ffit/funcs/exp.py

class Exp(FitLogic[ExpResult]):  # type: ignore
    r"""Exp function.


    Function
    ---------

    $$
        f(x) = A \exp(Γ⋅x) + A_{\text{offset}}
    $$

        f(x) = amplitude * np.exp(rate * x) + offset


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

    """

    _result_class: _t.Type[ExpResult] = ExpResult

    func = staticmethod(exp_func)
    func_std = staticmethod(exp_error)
    _guess = staticmethod(exp_guess)

    _example_param = (-3, -0.5, 3)
    _example_x_min = 0
    _example_x_max = 10

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

    @classmethod
    def mask(cls, **kwargs) -> "Exp":
        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[_ARRAY]	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[_ARRAY] = 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)
    if len(x) != len(data):
        raise ValueError("x and data must have the same length")
    if mask is not None and len(mask) != len(x):
        raise ValueError("mask must have the same length as x and 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[_ARRAY] = 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[_ARRAY]	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[_ARRAY] = 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, maxfev=_DEFAULT_MAXFEV, **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[_ARRAY]	The mask array or threshold for data filtering (optional).	None
guess	Optional[Union[_T, _ANY_LIST_LIKE]]	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'
num_of_permutations	Optional[int]	The number of permutations to use for the bootstrapping.	None
maxfev	int	The maximum number of function evaluations.	_DEFAULT_MAXFEV
**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[_ARRAY] = None,
    guess: _t.Optional[_t.Union[_T, _ANY_LIST_LIKE]] = None,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    num_of_permutations: _t.Optional[int] = None,
    maxfev: int = _DEFAULT_MAXFEV,
    **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").
        num_of_permutations: The number of permutations to use for the bootstrapping.
        maxfev: The maximum number of function evaluations.
        **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_means, total_std = self._bootstrapping(
        x, data, mask, guess, method, num_of_permutations, maxfev
    )

    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,
        stderr=total_std,  # type: ignore
        stdfunc=lambda x: self.get_func_std()(x, *res_means, *total_std),
        original_func=self.func,
    )

array_bootstrapping

array_bootstrapping(x, data, *, mask=None, guess=None, axis=-1, method='leastsq', maxfev=10000, num_of_permutations=None, **kwargs)

Perform array bootstrapping in parallel.

Parameters:

Name	Type	Description	Default
x	_ARRAY	The independent variable.	required
data	_2DARRAY	The dependent variable.	required
mask	Optional[_ARRAY]	The mask array or threshold for data filtering (optional).	None
guess	Optional[Union[_T, tuple, list]]	The initial guess for fit parameters (optional).	None
axis	int	The axis along which to perform the fit (default: -1).	-1
method	Literal['least_squares', 'leastsq', 'curve_fit']	The fitting method to use (default: "leastsq").	'leastsq'
maxfev	int	Maximum number of function evaluations (default: 10000).	10000
num_of_permutations	Optional[int]	Number of bootstrap iterations.	None
**kwargs		Additional keyword arguments passed to _fit.	{}

Returns:

Name	Type	Description
FitResult	_T	The result of the bootstrapping.

Source code in ffit/fit_logic.py

def array_bootstrapping(
    self,
    x: _ARRAY,
    data: _2DARRAY,
    *,
    mask: _t.Optional[_ARRAY] = None,
    guess: _t.Optional[_t.Union[_T, tuple, list]] = None,
    axis: int = -1,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    maxfev: int = 10000,
    num_of_permutations: _t.Optional[int] = None,
    **kwargs,
) -> _T:
    """Perform array bootstrapping in parallel.

    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).
        axis: The axis along which to perform the fit (default: -1).
        method: The fitting method to use (default: "leastsq").
        maxfev: Maximum number of function evaluations (default: 10000).
        num_of_permutations: Number of bootstrap iterations.
        **kwargs: Additional keyword arguments passed to _fit.

    Returns:
        FitResult: The result of the bootstrapping.
    """
    x, data, multi_x, data_shape, x_shape, selected_axis_len = (
        self._prepare_array_data(x, data, axis)
    )

    # Run bootstrapping on each dataset
    results = np.array(
        [
            self._bootstrapping(
                x[i] if multi_x else x,
                data[i],
                mask=mask,
                guess=guess,
                method=method,
                num_of_permutations=num_of_permutations,
                maxfev=maxfev,
                **kwargs,
            )
            for i in range(len(data))
        ]
    )

    # Split means and stds from results
    result_means = results[:, 0, :]  # First element of each result is means
    result_stds = results[:, 1, :]  # Second element is standard deviations

    # Reshape results back to original data shape
    result_means = result_means.reshape(data_shape[:-1] + (-1,))
    result_stds = result_stds.reshape(data_shape[:-1] + (-1,))

    if multi_x:
        x = x.reshape(x_shape)

    return self._result_class(
        result_means,
        self._create_array_res_func(
            result_means, multi_x, data_shape, selected_axis_len
        ),
        x=x,
        data=data,
        stderr=result_stds,
        stdfunc=lambda x: self.get_func_std()(x, *result_means, *result_stds),
        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[_ARRAY]	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[_ARRAY] = 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,
    )

mp_array_fit

mp_array_fit(x, data, *, mask=None, guess=None, axis=-1, method='leastsq', maxfev=10000, n_jobs=None, **kwargs)

Perform array fitting in parallel using multiprocessing.

Parameters:

Name	Type	Description	Default
x	_ARRAY	The independent variable.	required
data	_2DARRAY	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
axis	int	The axis along which to perform the fit (default: -1).	-1
method	Literal['least_squares', 'leastsq', 'curve_fit']	The fitting method to use (default: "leastsq").	'leastsq'
maxfev	int	Maximum number of function evaluations (default: 10000).	10000
n_jobs	Optional[int]	Number of processes to use. If None, uses cpu_count().	None
**kwargs		Additional keyword arguments passed to _fit.	{}

Returns:

Name	Type	Description
FitResult	_T	The result of the fit.

Source code in ffit/fit_logic.py

def mp_array_fit(
    self,
    x: _ARRAY,
    data: _2DARRAY,
    *,
    mask: _t.Optional[_t.Union[_ARRAY, float]] = None,
    guess: _t.Optional[_t.Union[_T, tuple, list]] = None,
    axis: int = -1,
    method: _t.Literal["least_squares", "leastsq", "curve_fit"] = "leastsq",
    maxfev: int = 10000,
    n_jobs: _t.Optional[int] = None,
    **kwargs,
) -> _T:
    """Perform array fitting in parallel using multiprocessing.

    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).
        axis: The axis along which to perform the fit (default: -1).
        method: The fitting method to use (default: "leastsq").
        maxfev: Maximum number of function evaluations (default: 10000).
        n_jobs: Number of processes to use. If None, uses cpu_count().
        **kwargs: Additional keyword arguments passed to _fit.

    Returns:
        FitResult: The result of the fit.
    """
    import multiprocessing as mp

    x, data, multi_x, data_shape, x_shape, selected_axis_len = (
        self._prepare_array_data(x, data, axis)
    )

    # Prepare arguments for parallel processing
    fit_args = [
        (x[i] if multi_x else x, data[i], mask, guess, method, maxfev, kwargs)
        for i in range(len(data))
    ]

    # Run fits in parallel using multiprocessing
    with mp.Pool(processes=n_jobs) as pool:
        results = pool.map(self._fit_worker, fit_args)

    results = np.array(results).reshape(data_shape[:-1] + (-1,))

    if multi_x:
        x = x.reshape(x_shape)

    return self._result_class(
        results,
        self._create_array_res_func(
            results, multi_x, data_shape, selected_axis_len
        ),
        x=x,
        data=data,
        original_func=self.func,
    )