Core

`FitResult`

Stores the result of a fitting procedure.

This class encapsulates the fitted parameters, their standard errors, optimizer output, and fit quality metrics. It also provides functionality for summarizing the results and making predictions using the fitted model.

Parameters:

Name	Type	Description	Default
`params`	`dict`	Array of fitted parameters.	required
`std_err`	`dict`	Array of standard errors of the fitted parameters.	required
`fit_output`	`any`	Raw output from the optimization routine.	required
`metrics`	`dict`	Dictionary of fit quality metrics (e.g., R-squared, reduced chi-squared).	`{}`
`predict`	`callable`	Function of x that returns predictions based on the fitted parameters. If not provided, an exception will be raised when calling it.	`None`
`param_names`	`list`	List of parameter names, defaulting to a range based on the number of parameters.	`None`
`model_name`	`str`	Name of the model used to fit the data.	`None`
`metadata`	`dict`	Additional information that can be passed in the fit result.	`{}`

Methods:

Name	Description
`summary`	Prints a detailed summary of the fit results, including parameter values, standard errors, and fit quality metrics.
`_no_prediction`	Raises an exception when no prediction function is available.

Source code in sqil_core/fit/_core.py

class FitResult:
    """
    Stores the result of a fitting procedure.

    This class encapsulates the fitted parameters, their standard errors, optimizer output,
    and fit quality metrics. It also provides functionality for summarizing the results and
    making predictions using the fitted model.

    Parameters
    ----------
    params : dict
        Array of fitted parameters.
    std_err : dict
        Array of standard errors of the fitted parameters.
    fit_output : any
        Raw output from the optimization routine.
    metrics : dict, optional
        Dictionary of fit quality metrics (e.g., R-squared, reduced chi-squared).
    predict : callable, optional
        Function of x that returns predictions based on the fitted parameters.
        If not provided, an exception will be raised when calling it.
    param_names : list, optional
        List of parameter names, defaulting to a range based on the number of parameters.
    model_name : str, optional
        Name of the model used to fit the data.
    metadata : dict, optional
        Additional information that can be passed in the fit result.

    Methods
    -------
    summary()
        Prints a detailed summary of the fit results, including parameter values,
        standard errors, and fit quality metrics.
    _no_prediction()
        Raises an exception when no prediction function is available.
    """

    def __init__(
        self,
        params,
        std_err,
        fit_output,
        metrics={},
        predict=None,
        param_names=None,
        model_name=None,
        metadata={},
    ):
        self.params = params
        self.std_err = std_err
        self.output = fit_output
        self.metrics = metrics
        self.predict = predict or self._no_prediction
        self.param_names = param_names or list(range(len(params)))
        self.model_name = model_name
        self.metadata = metadata

        self.params_by_name = dict(zip(self.param_names, self.params))

    def __repr__(self):
        return (
            f"FitResult(\n"
            f"  params={self.params},\n"
            f"  std_err={self.std_err},\n"
            f"  metrics={self.metrics}\n)"
        )

    def summary(self, no_print=False):
        """Prints a detailed summary of the fit results."""
        s = format_fit_metrics(self.metrics) + "\n"
        s += format_fit_params(
            self.param_names,
            self.params,
            self.std_err,
            np.array(self.std_err) / self.params * 100,
        )
        if not no_print:
            print(s)
        return s

    def quality(self, recipe="nrmse"):
        return evaluate_fit_quality(self.metrics, recipe)

    def is_acceptable(self, recipe="nrmse", threshold=FitQuality.ACCEPTABLE):
        return self.quality(recipe) >= threshold

    def _no_prediction(self):
        raise Exception("No predition function available")

`summary(no_print=False)`

Prints a detailed summary of the fit results.

Source code in sqil_core/fit/_core.py

def summary(self, no_print=False):
    """Prints a detailed summary of the fit results."""
    s = format_fit_metrics(self.metrics) + "\n"
    s += format_fit_params(
        self.param_names,
        self.params,
        self.std_err,
        np.array(self.std_err) / self.params * 100,
    )
    if not no_print:
        print(s)
    return s

`compute_adjusted_standard_errors(pcov, residuals, red_chi2=None, cov_rescaled=True, sigma=None)`

Compute adjusted standard errors for fitted parameters.

This function adjusts the covariance matrix based on the reduced chi-squared value and calculates the standard errors for each parameter. It accounts for cases where the covariance matrix is not available or the fit is nearly perfect.

Parameters:

Name	Type	Description	Default
`pcov`	`ndarray`	Covariance matrix of the fitted parameters, typically obtained from an optimization routine.	required
`residuals`	`ndarray`	Residuals of the fit, defined as the difference between observed and model-predicted values.	required
`red_chi2`	`float`	Precomputed reduced chi-squared value. If `None`, it is computed from `residuals` and `sigma`.	`None`
`cov_rescaled`	`bool`	Whether the fitting process already rescales the covariance matrix with the reduced chi-squared.	`True`
`sigma`	`ndarray`	Experimental uncertainties. Only used if `cov_rescaled=False` AND known experimental errors are available.	`None`

Returns:

Type	Description
`ndarray`	Standard errors for each fitted parameter. If the covariance matrix is undefined, returns `None`.

Warnings

If the covariance matrix is not available (pcov is None), the function issues a warning about possible numerical instability or a near-perfect fit.
If the reduced chi-squared value is NaN, the function returns NaN for all standard errors.

Notes

The covariance matrix is scaled by the reduced chi-squared value to adjust for under- or overestimation of uncertainties.
If red_chi2 is not provided, it is computed internally using the residuals.
If a near-perfect fit is detected (all residuals close to zero), the function warns that standard errors may not be necessary.

Examples:

>>> pcov = np.array([[0.04, 0.01], [0.01, 0.09]])
>>> residuals = np.array([0.1, -0.2, 0.15])
>>> compute_adjusted_standard_errors(pcov, residuals)
array([0.2, 0.3])

Source code in sqil_core/fit/_core.py

def compute_adjusted_standard_errors(
    pcov: np.ndarray,
    residuals: np.ndarray,
    red_chi2=None,
    cov_rescaled=True,
    sigma=None,
) -> np.ndarray:
    """
    Compute adjusted standard errors for fitted parameters.

    This function adjusts the covariance matrix based on the reduced chi-squared
    value and calculates the standard errors for each parameter. It accounts for
    cases where the covariance matrix is not available or the fit is nearly perfect.

    Parameters
    ----------
    pcov : np.ndarray
        Covariance matrix of the fitted parameters, typically obtained from an
        optimization routine.
    residuals : np.ndarray
        Residuals of the fit, defined as the difference between observed and
        model-predicted values.
    red_chi2 : float, optional
        Precomputed reduced chi-squared value. If `None`, it is computed from
        `residuals` and `sigma`.
    cov_rescaled : bool, default=True
        Whether the fitting process already rescales the covariance matrix with
        the reduced chi-squared.
    sigma : np.ndarray, optional
        Experimental uncertainties. Only used if `cov_rescaled=False` AND
        known experimental errors are available.

    Returns
    -------
    np.ndarray
        Standard errors for each fitted parameter. If the covariance matrix is
        undefined, returns `None`.

    Warnings
    --------
    - If the covariance matrix is not available (`pcov is None`), the function
      issues a warning about possible numerical instability or a near-perfect fit.
    - If the reduced chi-squared value is `NaN`, the function returns `NaN` for
      all standard errors.

    Notes
    -----
    - The covariance matrix is scaled by the reduced chi-squared value to adjust
      for under- or overestimation of uncertainties.
    - If `red_chi2` is not provided, it is computed internally using the residuals.
    - If a near-perfect fit is detected (all residuals close to zero), the function
      warns that standard errors may not be necessary.

    Examples
    --------
    >>> pcov = np.array([[0.04, 0.01], [0.01, 0.09]])
    >>> residuals = np.array([0.1, -0.2, 0.15])
    >>> compute_adjusted_standard_errors(pcov, residuals)
    array([0.2, 0.3])
    """
    # Check for invalid covariance
    if pcov is None:
        if np.allclose(residuals, 0, atol=1e-10):
            warnings.warn(
                "Covariance matrix could not be estimated due to an almost perfect fit. "
                "Standard errors are undefined but may not be necessary in this case."
            )
        else:
            warnings.warn(
                "Covariance matrix could not be estimated. This could be due to poor model fit "
                "or numerical instability. Review the data or model configuration."
            )
        return None

    # Calculate reduced chi-squared
    n_params = len(np.diag(pcov))
    if red_chi2 is None:
        _, red_chi2 = compute_chi2(
            residuals, n_params, cov_rescaled=cov_rescaled, sigma=sigma
        )

    # Rescale the covariance matrix
    if np.isnan(red_chi2):
        pcov_rescaled = np.nan
    else:
        pcov_rescaled = pcov * red_chi2

    # Calculate standard errors for each parameter
    if np.any(np.isnan(pcov_rescaled)):
        standard_errors = np.full(n_params, np.nan, dtype=float)
    else:
        standard_errors = np.sqrt(np.diag(pcov_rescaled))

    return standard_errors

`compute_aic(residuals, n_params)`

Computes the Akaike Information Criterion (AIC) for a given model fit.

The AIC is a metric used to compare the relative quality of statistical models for a given dataset. It balances model fit with complexity, penalizing models with more parameters to prevent overfitting.

Interpretation: The AIC has no maeaning on its own, only the difference between the AIC of model1 and the one of model2. ΔAIC = AIC_1 - AIC_2 If ΔAIC > 10 -> model 2 fits much better.

Parameters:

Name	Type	Description	Default
`residuals`	`ndarray`	Array of residuals between the observed data and model predictions.	required
`n_params`	`int`	Number of free parameters in the fitted model.	required

Returns:

Type	Description
`float`	The Akaike Information Criterion value.

Source code in sqil_core/fit/_core.py

def compute_aic(residuals: np.ndarray, n_params: int) -> float:
    """
    Computes the Akaike Information Criterion (AIC) for a given model fit.

    The AIC is a metric used to compare the relative quality of statistical models
    for a given dataset. It balances model fit with complexity, penalizing models
    with more parameters to prevent overfitting.

    Interpretation: The AIC has no maeaning on its own, only the difference between
    the AIC of model1 and the one of model2.
    ΔAIC = AIC_1 - AIC_2
    If ΔAIC > 10 -> model 2 fits much better.

    Parameters
    ----------
    residuals : np.ndarray
        Array of residuals between the observed data and model predictions.
    n_params : int
        Number of free parameters in the fitted model.

    Returns
    -------
    float
        The Akaike Information Criterion value.
    """

    n = len(residuals)
    rss = np.sum(residuals**2)
    return 2 * n_params + n * np.log(rss / n)

`compute_chi2(residuals, n_params=None, cov_rescaled=True, sigma=None)`

Compute the chi-squared (χ²) and reduced chi-squared (χ²_red) statistics.

This function calculates the chi-squared value based on residuals and an estimated or provided uncertainty (sigma). If the number of model parameters (n_params) is specified, it also computes the reduced chi-squared.

Parameters:

Name	Type	Description	Default
`residuals`	`ndarray`	The difference between observed and model-predicted values.	required
`n_params`	`int`	Number of fitted parameters. If provided, the function also computes the reduced chi-squared (χ²_red).	`None`
`cov_rescaled`	`bool`	Whether the covariance matrix has been already rescaled by the fit method. If `True`, the function assumes proper uncertainty scaling. Otherwise, it estimates uncertainty from the standard deviation of the residuals.	`True`
`sigma`	`ndarray`	Experimental uncertainties. Should only be used when the fitting process does not account for experimental errors AND known uncertainties are available.	`None`

Returns:

Name	Type	Description
`chi2`	`float`	The chi-squared statistic (χ²), which measures the goodness of fit.
`red_chi2`	float (if `n_params` is provided)	The reduced chi-squared statistic (χ²_red), computed as χ² divided by the degrees of freedom (N - p). If `n_params` is `None`, only χ² is returned.

Warnings

If the degrees of freedom (N - p) is non-positive, a warning is issued, and χ²_red is set to NaN. This may indicate overfitting or an insufficient number of data points.
If any uncertainty value in sigma is zero, it is replaced with machine epsilon to prevent division by zero.

Notes

If sigma is not provided and cov_rescaled=False, the function estimates the uncertainty using the standard deviation of residuals.
The reduced chi-squared value (χ²_red) should ideally be close to 1 for a good fit. Values significantly greater than 1 indicate underfitting, while values much less than 1 suggest overfitting.

Examples:

>>> residuals = np.array([0.1, -0.2, 0.15, -0.05])
>>> compute_chi2(residuals, n_params=2)
(0.085, 0.0425)  # Example output

Source code in sqil_core/fit/_core.py

def compute_chi2(residuals, n_params=None, cov_rescaled=True, sigma: np.ndarray = None):
    """
    Compute the chi-squared (χ²) and reduced chi-squared (χ²_red) statistics.

    This function calculates the chi-squared value based on residuals and an
    estimated or provided uncertainty (`sigma`). If the number of model parameters
    (`n_params`) is specified, it also computes the reduced chi-squared.

    Parameters
    ----------
    residuals : np.ndarray
        The difference between observed and model-predicted values.
    n_params : int, optional
        Number of fitted parameters. If provided, the function also computes
        the reduced chi-squared (χ²_red).
    cov_rescaled : bool, default=True
        Whether the covariance matrix has been already rescaled by the fit method.
        If `True`, the function assumes proper uncertainty scaling. Otherwise,
        it estimates uncertainty from the standard deviation of the residuals.
    sigma : np.ndarray, optional
        Experimental uncertainties. Should only be used when the fitting process
        does not account for experimental errors AND known uncertainties are available.

    Returns
    -------
    chi2 : float
        The chi-squared statistic (χ²), which measures the goodness of fit.
    red_chi2 : float (if `n_params` is provided)
        The reduced chi-squared statistic (χ²_red), computed as χ² divided by
        the degrees of freedom (N - p). If `n_params` is `None`, only χ² is returned.

    Warnings
    --------
    - If the degrees of freedom (N - p) is non-positive, a warning is issued,
      and χ²_red is set to NaN. This may indicate overfitting or an insufficient
      number of data points.
    - If any uncertainty value in `sigma` is zero, it is replaced with machine epsilon
      to prevent division by zero.

    Notes
    -----
    - If `sigma` is not provided and `cov_rescaled=False`, the function estimates
      the uncertainty using the standard deviation of residuals.
    - The reduced chi-squared value (χ²_red) should ideally be close to 1 for a good fit.
      Values significantly greater than 1 indicate underfitting, while values much less
      than 1 suggest overfitting.

    Examples
    --------
    >>> residuals = np.array([0.1, -0.2, 0.15, -0.05])
    >>> compute_chi2(residuals, n_params=2)
    (0.085, 0.0425)  # Example output
    """
    # If the optimization does not account for th experimental sigma,
    # approximate it with the std of the residuals
    S = 1 if cov_rescaled else np.std(residuals)
    # If the experimental error is provided, use that instead
    if sigma is not None:
        S = sigma

    # Replace 0 elements of S with the machine epsilon to avoid divisions by 0
    if not np.isscalar(S):
        S_safe = np.where(S == 0, np.finfo(float).eps, S)
    else:
        S_safe = np.finfo(float).eps if S == 0 else S

    # Compute chi squared
    chi2 = np.sum((residuals / S_safe) ** 2)
    # If number of parameters is not provided return just chi2
    if n_params is None:
        return chi2

    # Reduced chi squared
    dof = len(residuals) - n_params  # degrees of freedom (N - p)
    if dof <= 0:
        warnings.warn(
            "Degrees of freedom (dof) is non-positive. This may indicate overfitting or insufficient data."
        )
        red_chi2 = np.nan
    else:
        red_chi2 = chi2 / dof

    return chi2, red_chi2

`compute_nrmse(residuals, y_data)`

Computes the Normalized Root Mean Squared Error (NRMSE) of a model fit.

Lower is better.

The NRMSE is a scale-independent metric that quantifies the average magnitude of residual errors normalized by the range of the observed data. It is useful for comparing the fit quality across different datasets or models.

For complex data it's computed using the L2 norm and the span of the magnitude.

Parameters:

Name	Type	Description	Default
`residuals`	`ndarray`	Array of residuals between the observed data and model predictions.	required
`y_data`	`ndarray`	The original observed data used in the model fitting.	required

Returns:

Type	Description
`float`	The normalized root mean squared error (NRMSE).

Source code in sqil_core/fit/_core.py

def compute_nrmse(residuals: np.ndarray, y_data: np.ndarray) -> float:
    """
    Computes the Normalized Root Mean Squared Error (NRMSE) of a model fit.

    Lower is better.

    The NRMSE is a scale-independent metric that quantifies the average magnitude
    of residual errors normalized by the range of the observed data. It is useful
    for comparing the fit quality across different datasets or models.

    For complex data it's computed using the L2 norm and the span of the magnitude.

    Parameters
    ----------
    residuals : np.ndarray
        Array of residuals between the observed data and model predictions.
    y_data : np.ndarray
        The original observed data used in the model fitting.

    Returns
    -------
    float
        The normalized root mean squared error (NRMSE).
    """
    n = len(residuals)
    if np.iscomplexobj(y_data):
        y_abs_span = np.max(np.abs(y_data)) - np.min(np.abs(y_data))
        if y_abs_span == 0:
            warnings.warn(
                "y_data has zero span in magnitude. NRMSE is undefined.", RuntimeWarning
            )
            return np.nan
        rmse = np.linalg.norm(residuals) / np.sqrt(n)
        nrmse = rmse / y_abs_span
    else:
        y_span = np.max(y_data) - np.min(y_data)
        if y_span == 0:
            warnings.warn("y_data has zero span. NRMSE is undefined.", RuntimeWarning)
            return np.nan
        rss = np.sum(residuals**2)
        nrmse = np.sqrt(rss / n) / y_span

    return nrmse

`fit_input(fit_func)`

Decorator to handle optional fitting inputs like initial guesses, bounds, and fixed parameters for a fitting function.

guess : list or np.ndarray, optional, default=None The initial guess for the fit. If None it's not passed to the fit function.
bounds : list or np.ndarray, optional, default=(-np.inf, np.inf) The bounds on the fit parameters in the form [(min, max), (min, max), ...].
fixed_params : list or np.ndarray, optional, default=None Indices of the parameters that must remain fixed during the optimization. For example fitting f(x, a, b), if we want to fix the value of a we would pass fit_f(guess=[a_guess, b_guess], fixed_params=[0])
fixed_bound_factor : float, optional, default=1e-6 The relative tolerance allowed for parameters that must remain fixed (fixed_params).

IMPORTANT: This decorator requires the x and y input vectors to be named x_data and y_data. The initial guess must be called guess and the bounds bounds.

Parameters:

Name	Type	Description	Default
`fit_func`	`callable`	The fitting function to be decorated. This function should accept `x_data` and `y_data` as mandatory parameters and may optionally accept `guess` and `bounds` (plus any other additional parameter).	required

Returns:

Type	Description
`callable`	A wrapper function that processes the input arguments and then calls the original fitting function with the preprocessed inputs. This function also handles warnings if unsupported parameters are passed to the fit function.

Notes

The parameters in guess, bounds and fixed_params must be in the same order as in the modeled function definition.
The decorator can fix certain parameters by narrowing their bounds based on an initial guess and a specified fixed_bound_factor.
The decorator processes bounds by setting them as (-np.inf, np.inf) if they are not specified (None).

Examples:

>>> @fit_input
... def my_fit_func(x_data, y_data, guess=None, bounds=None, fixed_params=None):
...     # Perform fitting...
...     return fit_result
>>> x_data = np.linspace(0, 10, 100)
>>> y_data = np.sin(x_data) + np.random.normal(0, 0.1, 100)
>>> result = my_fit_func(x_data, y_data, guess=[1, 1], bounds=[(0, 5), (-np.inf, np.inf)])

Source code in sqil_core/fit/_core.py

def fit_input(fit_func):
    """
    Decorator to handle optional fitting inputs like initial guesses, bounds, and fixed parameters
    for a fitting function.

    - `guess` : list or np.ndarray, optional, default=None
        The initial guess for the fit. If None it's not passed to the fit function.
    - `bounds` : list or np.ndarray, optional, default=(-np.inf, np.inf)
        The bounds on the fit parameters in the form [(min, max), (min, max), ...].
    - `fixed_params` : list or np.ndarray, optional, default=None
        Indices of the parameters that must remain fixed during the optimization.
        For example fitting `f(x, a, b)`, if we want to fix the value of `a` we would pass
        `fit_f(guess=[a_guess, b_guess], fixed_params=[0])`
    - `fixed_bound_factor` : float, optional, default=1e-6
        The relative tolerance allowed for parameters that must remain fixed (`fixed_params`).

    IMPORTANT: This decorator requires the x and y input vectors to be named `x_data` and `y_data`.
        The initial guess must be called `guess` and the bounds `bounds`.

    Parameters
    ----------
    fit_func : callable
        The fitting function to be decorated. This function should accept `x_data` and `y_data` as
        mandatory parameters and may optionally accept `guess` and `bounds` (plus any other additional
        parameter).

    Returns
    -------
    callable
        A wrapper function that processes the input arguments and then calls the original fitting
        function with the preprocessed inputs. This function also handles warnings if unsupported
        parameters are passed to the fit function.

    Notes
    -----
    - The parameters in `guess`, `bounds` and `fixed_params` must be in the same order as in the
      modeled function definition.
    - The decorator can fix certain parameters by narrowing their bounds based on an initial guess
      and a specified `fixed_bound_factor`.
    - The decorator processes bounds by setting them as `(-np.inf, np.inf)` if they are not specified (`None`).

    Examples
    -------
    >>> @fit_input
    ... def my_fit_func(x_data, y_data, guess=None, bounds=None, fixed_params=None):
    ...     # Perform fitting...
    ...     return fit_result
    >>> x_data = np.linspace(0, 10, 100)
    >>> y_data = np.sin(x_data) + np.random.normal(0, 0.1, 100)
    >>> result = my_fit_func(x_data, y_data, guess=[1, 1], bounds=[(0, 5), (-np.inf, np.inf)])
    """

    @wraps(fit_func)
    def wrapper(
        *params,
        guess=None,
        bounds=None,
        fixed_params=None,
        fixed_bound_factor=1e-6,
        sigma=None,
        **kwargs,
    ):
        # Inspect function to check if it requires guess and bounds
        func_params = inspect.signature(fit_func).parameters

        # Check if the user passed parameters that are not supported by the fit fun
        if (guess is not None) and ("guess" not in func_params):
            warnings.warn("The fit function doesn't allow any initial guess.")
        if (bounds is not None) and ("bounds" not in func_params):
            warnings.warn("The fit function doesn't allow any bounds.")
        if (fixed_params is not None) and (guess is None):
            raise ValueError("Using fixed_params requires an initial guess.")

        # Process bounds if the function accepts it
        if (bounds is not None) and ("bounds" in func_params):
            processed_bounds = np.array(
                [(-np.inf, np.inf) if b is None else b for b in bounds],
                dtype=np.float64,
            )
            lower_bounds, upper_bounds = (
                processed_bounds[:, 0],
                processed_bounds[:, 1],
            )
        else:
            lower_bounds, upper_bounds = None, None

        # Fix parameters by setting a very tight bound
        if (fixed_params is not None) and (guess is not None):
            if bounds is None:
                lower_bounds = -np.inf * np.ones(len(guess))
                upper_bounds = np.inf * np.ones(len(guess))
            for idx in fixed_params:
                tolerance = (
                    abs(guess[idx]) * fixed_bound_factor
                    if guess[idx] != 0
                    else fixed_bound_factor
                )
                lower_bounds[idx] = guess[idx] - tolerance
                upper_bounds[idx] = guess[idx] + tolerance

        # Prepare arguments dynamically
        fit_args = {**kwargs}

        if guess is not None and "guess" in func_params:
            fit_args["guess"] = guess
        if (
            (bounds is not None) or (fixed_params is not None)
        ) and "bounds" in func_params:
            fit_args["bounds"] = (lower_bounds, upper_bounds)

        # Call the wrapped function with preprocessed inputs
        fit_args = {**kwargs, **fit_args}
        return fit_func(*params, **fit_args)

    return wrapper

`fit_output(fit_func)`

Decorator to standardize the output of fitting functions.

This decorator processes the raw output of various fitting libraries (such as SciPy's curve_fit, least_squares leastsq, and minimize, as well as lmfit) and converts it into a unified FitResult object. It extracts optimized parameters, their standard errors, fit quality metrics, and a prediction function.

Parameters:

Name	Type	Description	Default
`fit_func`	`Callable`	A function that performs fitting and returns raw fit output, possibly along with metadata.	required

Returns:

Type Description

Callable

A wrapped function that returns a FitResult object containing: - params : list Optimized parameter values. - std_err : list or None Standard errors of the fitted parameters. - metrics : dict or None Dictionary of fit quality metrics (e.g., reduced chi-squared). - predict : Callable or None A function that predicts values using the optimized parameters. - output : object The raw optimizer output from the fitting process. - param_names : list or None Names of the fitted parameters. - metadata : dict A dictionary containing extra information. Advanced uses include passing functions that get evaluated after fit result has been processed. See the documentation, Notebooks/The fit_output decorator

Raises:

Type	Description
`TypeError`	If the fitting function's output format is not recognized.

Notes

If the fit function returns a tuple (raw_output, metadata), the metadata is extracted and applied to enhance the fit results. In case of any conflicts, the metadata overrides the computed values.

Examples:

>>> @fit_output
... def my_fitting_function(x, y):
...     return some_raw_fit_output
...
>>> fit_result = my_fitting_function(x_data, y_data)
>>> print(fit_result.params)

Source code in sqil_core/fit/_core.py

def fit_output(fit_func):
    """
    Decorator to standardize the output of fitting functions.

    This decorator processes the raw output of various fitting libraries
    (such as SciPy's curve_fit, least_squares leastsq, and minimize, as well as lmfit)
    and converts it into a unified `FitResult` object. It extracts
    optimized parameters, their standard errors, fit quality metrics,
    and a prediction function.

    Parameters
    ----------
    fit_func : Callable
        A function that performs fitting and returns raw fit output,
        possibly along with metadata.

    Returns
    -------
    Callable
        A wrapped function that returns a `FitResult` object containing:
        - `params` : list
            Optimized parameter values.
        - `std_err` : list or None
            Standard errors of the fitted parameters.
        - `metrics` : dict or None
            Dictionary of fit quality metrics (e.g., reduced chi-squared).
        - `predict` : Callable or None
            A function that predicts values using the optimized parameters.
        - `output` : object
            The raw optimizer output from the fitting process.
        - `param_names` : list or None
            Names of the fitted parameters.
        - `metadata` : dict
            A dictionary containing extra information. Advanced uses include passing
            functions that get evaluated after fit result has been processed.
            See the documentation, Notebooks/The fit_output decorator

    Raises
    ------
    TypeError
        If the fitting function's output format is not recognized.

    Notes
    -----
    - If the fit function returns a tuple `(raw_output, metadata)`,
      the metadata is extracted and applied to enhance the fit results.
      In case of any conflicts, the metadata overrides the computed values.

    Examples
    --------
    >>> @fit_output
    ... def my_fitting_function(x, y):
    ...     return some_raw_fit_output
    ...
    >>> fit_result = my_fitting_function(x_data, y_data)
    >>> print(fit_result.params)
    """

    @wraps(fit_func)
    def wrapper(*args, **kwargs):
        # Perform the fit
        fit_result = fit_func(*args, **kwargs)

        # Extract information from function arguments
        x_data, y_data = _get_xy_data_from_fit_args(*args, **kwargs)
        sigma = kwargs.get("sigma", None)
        has_sigma = isinstance(sigma, (list, np.ndarray))

        # Initilize variables
        sqil_keys = ["params", "std_err", "metrics", "predict", "output", "param_names"]
        sqil_dict = {key: None for key in sqil_keys}
        metadata = {}
        formatted = None
        # Set the default parameters to an empty array instead of None
        sqil_dict["params"] = []

        # Check if the fit output is a tuple and separate it into raw_fit_ouput and metadata
        if (
            isinstance(fit_result, tuple)
            and (len(fit_result) == 2)
            and isinstance(fit_result[1], dict)
        ):
            raw_fit_output, metadata = fit_result
        else:
            raw_fit_output = fit_result
        sqil_dict["output"] = raw_fit_output

        # Check if there are variables to override in metadata before continuing
        if "fit_output_vars" in metadata:
            overrides = metadata["fit_output_vars"]
            x_data = overrides.get("x_data", x_data)
            y_data = overrides.get("y_data", y_data)
            del metadata["fit_output_vars"]

        # Format the raw_fit_output into a standardized dict
        if raw_fit_output is None:
            raise TypeError("Fit didn't coverge, result is None")
        # Scipy tuple (curve_fit, leastsq)
        elif _is_scipy_tuple(raw_fit_output):
            formatted = _format_scipy_tuple(raw_fit_output, y_data, has_sigma=has_sigma)

        # Scipy least squares
        elif _is_scipy_least_squares(raw_fit_output):
            formatted = _format_scipy_least_squares(
                raw_fit_output, y_data, has_sigma=has_sigma
            )

        # Scipy minimize
        elif _is_scipy_minimize(raw_fit_output):
            residuals = None
            predict = metadata.get("predict", None)
            if (x_data is not None) and (predict is not None) and callable(predict):
                residuals = y_data - metadata["predict"](x_data, *raw_fit_output.x)
            formatted = _format_scipy_minimize(
                raw_fit_output, residuals=residuals, y_data=y_data, has_sigma=has_sigma
            )

        # lmfit
        elif _is_lmfit(raw_fit_output):
            formatted = _format_lmfit(raw_fit_output)

        # Custom fit output
        elif isinstance(raw_fit_output, dict):
            formatted = raw_fit_output

        else:
            raise TypeError(
                "Couldn't recognize the output.\n"
                + "Are you using scipy? Did you forget to set `full_output=True` in your fit method?"
            )

        # Update sqil_dict with the formatted fit_output
        if formatted is not None:
            sqil_dict.update(formatted)

        # Add/override fileds using metadata
        sqil_dict.update(metadata)

        # Process metadata
        metadata = _process_metadata(metadata, sqil_dict)
        # Remove fields already present in sqil_dict from metadata
        filtered_metadata = {k: v for k, v in metadata.items() if k not in sqil_keys}

        # Assign the optimized parameters to the prediction function
        model_name = metadata.get("model_name", None)
        if sqil_dict["predict"] is not None:
            if model_name is None:
                model_name = sqil_dict["predict"].__name__
            params = sqil_dict["params"]
            predict = sqil_dict["predict"]
            n_inputs = _count_function_parameters(predict)
            if n_inputs == 1 + len(params):
                sqil_dict["predict"] = lambda x: predict(x, *params)

        return FitResult(
            params=sqil_dict.get("params", []),
            std_err=sqil_dict.get("std_err", None),
            fit_output=raw_fit_output,
            metrics=sqil_dict.get("metrics", {}),
            predict=sqil_dict.get("predict", None),
            param_names=sqil_dict.get("param_names", None),
            model_name=model_name,
            metadata=filtered_metadata,
        )

    return wrapper