epyr.relaxation.fitting

T1/T2 relaxation fitting module.

Fit time-domain EPR relaxation data (T1 recovery, T2 echo decay) with mono-exponential, stretched-exponential, bi-exponential, inversion- or saturation-recovery, or combined homogeneous/spectral-diffusion models.

Functions

fit_multiple_decays(t_data, y_data[, ...])

Fit relaxation data with multiple models and compare by reduced chi-squared.

fit_relaxation(t_data, y_data[, model, ...])

Fit time-domain relaxation data with the specified decay/recovery model.

Classes

RelaxationFitComparison

Dict of model name to RelaxationFitResult, with a tabular __repr__.

RelaxationFitResult(model, parameters, ...)

Container for relaxation fit results.
class epyr.relaxation.fitting.RelaxationFitResult(model, parameters, parameter_errors, fitted_curve, residuals, r_squared, chi_squared, success, message, covariance_matrix=None, t_fit=None)[source]

Container for relaxation fit results.

Parameters:
model

Name of the fitted relaxation model.

Type:

str

parameters

Fitted parameter values keyed by parameter name.

Type:

dict

parameter_errors

Standard errors of fitted parameters (square root of covariance diagonal).

Type:

dict

fitted_curve

Model evaluated at the fitted points (t_fit).

Type:

np.ndarray

residuals

Data minus model at the fitted points.

Type:

np.ndarray

r_squared

Coefficient of determination R-squared.

Type:

float

chi_squared

Reduced chi-squared: sum of squared residuals divided by degrees of freedom.

Type:

float

success

True if curve_fit converged.

Type:

bool

message

Convergence message or error description.

Type:

str

covariance_matrix

Full parameter covariance matrix returned by curve_fit.

Type:

np.ndarray or None

t_fit

Time values used for fitting, after NaN removal and masking.

Type:

np.ndarray or None

model: str
parameters: Dict[str, float]
parameter_errors: Dict[str, float]
fitted_curve: ndarray
residuals: ndarray
r_squared: float
chi_squared: float
success: bool
message: str
covariance_matrix: ndarray | None = None
t_fit: ndarray | None = None
summary()[source]

Return a formatted string summarizing fit quality and parameters.

Return type:

str

__init__(model, parameters, parameter_errors, fitted_curve, residuals, r_squared, chi_squared, success, message, covariance_matrix=None, t_fit=None)
Parameters:
Return type:

None

epyr.relaxation.fitting.fit_relaxation(t_data, y_data, model='mono_exponential', initial_params=None, bounds=None, mask=None, plot=True, time_unit='', **fit_kwargs)[source]

Fit time-domain relaxation data with the specified decay/recovery model.

Parameters:

  • t_data (np.ndarray) – Time axis, in the unit chosen by the caller (e.g. ns or us).

  • y_data (np.ndarray) – Relaxation signal (real-valued; take np.abs() of a complex echo signal before calling this function).

  • model (str, optional) – Relaxation model name (default: ‘mono_exponential’). See SUPPORTED_MODELS for the full list as models are added.

  • initial_params (dict, optional) – Initial parameter guesses. Auto-estimated from data if None.

  • bounds (dict, optional) – Parameter bounds as {name: (lower, upper)}, overriding data-derived defaults.

  • mask (np.ndarray of bool, optional) – Boolean array of the same length as t_data. True selects a point for fitting; False excludes it. If None, all non-NaN points are used.

  • plot (bool, optional) – Display a fit plot with residuals panel (default: True).

  • time_unit (str, optional) – Cosmetic time-unit label for the plot axis and summary (e.g. ‘ns’). Does not affect fitting (default: ‘’).

  • **fit_kwargs – Additional keyword arguments passed to scipy.optimize.curve_fit.

Returns:

Fit parameters, errors, statistics, fitted curve, and residuals.

Return type:

RelaxationFitResult

Examples

>>> from epyr.relaxation import fit_relaxation
>>> import numpy as np
>>> t = np.linspace(0, 100, 200)
>>> y = 5.0 * np.exp(-t / 15.0) + 1.0
>>> result = fit_relaxation(t, y, 'mono_exponential', plot=False)
>>> print(result.summary())
class epyr.relaxation.fitting.RelaxationFitComparison[source]

Dict of model name to RelaxationFitResult, with a tabular __repr__.

Behaves exactly like a plain dict (subscripting, iteration, .items(), …). Printing it shows R-squared, chi-squared, and every fitted parameter side by side for all models, so the full comparison is visible without looping over individual summary() calls.

epyr.relaxation.fitting.fit_multiple_decays(t_data, y_data, models=None, mask=None, plot=True)[source]

Fit relaxation data with multiple models and compare by reduced chi-squared.

Parameters:

  • t_data (np.ndarray) – Time axis, in the unit chosen by the caller.

  • y_data (np.ndarray) – Relaxation signal.

  • models (list of str, optional) – Models to fit. Default: [‘mono_exponential’, ‘stretched_exponential’, ‘biexponential’]. The recovery models and ‘gamma_gaussian_decay’ are excluded by default since they assume a specific data shape rather than being interchangeable candidates for a generic decay.

  • mask (np.ndarray of bool, optional) – Boolean array selecting points to include (True = include). Passed unchanged to each fit_relaxation call.

  • plot (bool, optional) – Display a side-by-side comparison plot (default: True).

Returns:

Dict subclass mapping model name to RelaxationFitResult for all attempted fits. Printing it shows a comparison table of R-squared, chi-squared, and every fitted parameter across all models.

Return type:

RelaxationFitComparison

Notes

Models are ranked by reduced chi-squared, not R-squared: R-squared is biased toward models with more free parameters, since extra parameters can only reduce the residual sum of squares on the same data.