Skip to content

fitting#

Curve fitting with automatic method selection.

Fit a model — one of the built-in models (e.g. models.exponential_decay) or your own function — to a signal, spectrum, or raw (x, y) arrays. The fitter inspects the model and the data and picks an appropriate algorithm and starting guess for you, so most calls are just fitting.fit(data, model).

analyze_model #

analyze_model(model: Callable) -> FunctionAnalysisResult

Inspect a model function and report how it will be fitted.

Examines a model to detect its type (e.g. exponential, sigmoid) and which algorithm and starting guess the fitter would choose. Useful for understanding or debugging an automatic fit without running it.

Parameters:

Name Type Description Default
model Callable

The model function to inspect.

 required

Returns:

Type Description
FunctionAnalysisResult

An analysis object describing the detected function type, the
FunctionAnalysisResult

confidence of that detection, and the recommended fitting approach.

fit #

fit(
    data: Signal1D | Spectrum1D | tuple[ndarray, ndarray],
    model: Callable,
    initial_guess: tuple[float, Ellipsis] | None = None,
    method: Literal[
        "auto", "robust", "fast", "accurate"
    ] = "auto",
    algorithm: Literal[
        "scipy", "linear", "varpro", "specialized"
    ]
    | None = None,
    n_components: int = 1,
    **kwargs: Any,
) -> SmartFittingResult

Fit a model to data, choosing the best algorithm automatically.

The main entry point for fitting. It analyses the model function and the data, picks a suitable algorithm and an initial parameter guess (unless you supply one), runs the fit, and returns the fitted parameters along with quality information.

Parameters:

Name Type Description Default
data Signal1D | Spectrum1D | tuple[ndarray, ndarray]

The data to fit — a Signal1D, a Spectrum1D, or a raw (x, y) pair of arrays.

 required
model Callable

The model function, taking (x, *params) and returning the predicted y. Use a built-in (e.g. models.exponential_decay) or your own.

 required
initial_guess tuple[float, Ellipsis] | None

Starting values for the parameters. Estimated automatically when omitted.

 None
method Literal['auto', 'robust', 'fast', 'accurate']

Fitting strategy — "auto" (let the fitter decide), "robust" (tolerate outliers, slower), "fast" (prioritise speed), or "accurate" (prioritise precision, slower).

 'auto'
algorithm Literal['scipy', 'linear', 'varpro', 'specialized'] | None

Force a specific algorithm instead of auto-selecting. Leave as None unless you know you need a particular one.

 None
n_components int

For multi-component models (e.g. multi-exponential), how many components to fit.

 1
**kwargs Any

Extra options forwarded to the underlying fitter.

 {}

Returns:

Type Description
SmartFittingResult

A result object whose main fields are:
SmartFittingResult
  • parameters: the fitted parameter values.
SmartFittingResult
  • loss: the final fit error (lower is better).
SmartFittingResult
  • data_info: data diagnostics (e.g. data_info.snr_estimate).
SmartFittingResult
  • model_info: what the fitter detected (e.g. model_info.function_type).

Examples:

# Built-in exponential model on the current signal
result = fitting.fit(my_signal, models.exponential_decay)
result.parameters


# Your own model function
def my_model(x, a, b, c):
    return a * np.exp(-x / b) + c


result = fitting.fit(my_signal, my_model)

# Two-component exponential fit
result = fitting.fit(my_signal, models.exponential_decay, n_components=2)

get_predefined_models #

get_predefined_models() -> dict[str, Callable]

List the built-in model functions by name.

The same models are also available directly on the models namespace (e.g. models.exponential_decay); this returns them as a lookup table, handy for choosing a model by name in a loop.

Returns:

Type Description
dict[str, Callable]

A mapping of model name to its function.

predict #

predict(
    x_data: ndarray,
    model: Callable,
    parameters: tuple[float, Ellipsis] | list[float],
) -> ndarray

Evaluate a model on new x values using known parameters.

Use after fit to draw the fitted curve on a finer or wider grid, or to evaluate any model with parameters you already have.

Parameters:

Name Type Description Default
x_data ndarray

X values to evaluate the model at.

 required
model Callable

The model function, the same one used to fit.

 required
parameters tuple[float, Ellipsis] | list[float]

The parameter values to plug in (e.g. result.parameters).

 required

Returns:

Type Description
ndarray

The predicted y values, one per element of x_data.
Example 
x_new = np.linspace(0, 10, 100)
y_fit = fitting.predict(x_new, models.exponential_decay, result.parameters)