Fitting (labtoolbox.fit)#

Model fitting utilities for LabToolbox.

Exposes linear and generic model fitting routines along with bootstrap fitting.

labtoolbox.fit.bootstrap_fit(*args, **kwargs)[source]#

Legacy bootstrap fit; removed in favor of scipy.stats.bootstrap functionality.

Deprecated since version 3.1.0: Use scipy.stats.bootstrap() instead or implement custom fit workflows.

labtoolbox.fit.lin_fit(x, y, y_err, x_err=None, fitmodel='wls', xlabel='x [ux]', ylabel='y [uy]', xlim=None, ylim=None, showlegend=True, legendloc=None, log=None, xscale=0, yscale=0, mscale=0, cscale=0, m_units='', c_units='', confidence=2, confidencerange=True, residuals=True, norm=True, verbose=False, summary=True)[source]#

Performs a linear fit (Weighted Least Squares or Ordinary Least Squares) and displays experimental data along with the regression line and uncertainty band.

Parameters:

  • x (array-like) – Values of the independent variable.

  • y (array-like) – Values of the dependent variable.

  • y_err (array-like) – Uncertainties associated with y values.

  • x_err (array-like, optional) – Uncertainties associated with x values.

  • fitmodel (str, optional) – Fitting model, either “wls” or “ols”. Default is “wls”.

  • xlabel (str, optional) – Label for the x-axis, including units in square brackets (e.g., “x [m]”).

  • ylabel (str, optional) – Label for the y-axis, including units in square brackets (e.g., “y [s]”).

  • showlegend (bool, optional) – If True, displays a legend with the values of m and c on the plot.

  • legendloc (str, optional) – Location of the legend on the plot (‘upper right’, ‘lower left’, ‘upper center’, etc.). Default is None.

  • log (str, optional) – If set to ‘x’ or ‘y’, the corresponding axis is plotted on a logarithmic scale; if ‘xy’, both axes. Default is None.

  • xscale (int, optional) – Scaling factor for the x-axis (e.g., xscale = -2 corresponds to 1e-2, to convert meters to centimeters).

  • yscale (int, optional) – Scaling factor for the y-axis.

  • xlim (tuple, optional) – Limits for the x-axis, in the form (xmin, xmax). The values should already be scaled with respect to xscale. If None or an empty tuple, the default limits will be automatically determined from the data.

  • ylim (tuple, optional) – Limits for the y-axis, in the form (ymin, ymax). The values should already be scaled with respect to yscale. If None or an empty tuple, the default limits will be automatically determined from the data.

  • mscale (int, optional) – Scaling factor for the slope m.

  • cscale (int, optional) – Scaling factor for the intercept c.

  • m_units (str, optional) – Unit of measurement for m. Default is “”.

  • c_units (str, optional) – Unit of measurement for c. Default is “”.

  • confidence (int, optional) – Residual confidence interval to display, i.e., [-confidence, +confidence].

  • confidencerange (bool, optional) – If True, shows the 1σ uncertainty band around the fit line.

  • residuals (bool, optional) – If True, adds an upper panel showing fit residuals.

  • norm (bool, optional) – If True, residuals in the upper panel will be normalized.

  • verbose (bool, optional) – If True, prints the output of wls_fit (or ols_fit) to the screen. Default is False.

  • summary (bool, optional) – If True, prints a formatted summary report of the fit, including reduced chi-square, p-value, and percentage of residuals within ±2σ.

Returns:

  • m (float) – Slope of the regression line.

  • c (float) – Intercept of the regression line.

  • sigma_m (float) – Uncertainty on the slope.

  • sigma_c (float) – Uncertainty on the intercept.

  • chi2_red (float) – Reduced chi-square value (χ²/dof).

  • p_value (float) – Fit p-value.

Notes

  • The values of xscale and yscale affect only the axis scaling in the plot and have no impact on the fitting computation itself. All model parameters are estimated using the original i_nput data as provided.

  • LaTeX formatting is already embedded in the strings used to display the units of m and c. You do not need to use “$…$”.

  • If c_scale = 0 (recommended when using c_units), then c_units will represent the suffix corresponding to 10^yscale (+ y_units).

  • If m_scale = 0 (recommended when using m_units), then m_units will represent the suffix corresponding to 10^(yscale - xscale) [+ y_units/x_units].

labtoolbox.fit.model_fit(x, y, f, x_err=None, y_err=None, p0=None, xlabel='x [ux]', ylabel='y [uy]', xlim=None, ylim=None, showlegend=True, legendloc=None, bounds=None, confidencerange=True, log=None, maxfev=5000, xscale=0, yscale=0, confidence=2, residuals=True, norm=True, verbose=True, print_parameters=True)[source]#

General-purpose fit of multi-parameter functions.

Parameters:

  • x (array-like) – Measured values of the independent variable.

  • y (array-like) – Measured values of the dependent variable.

  • f (function) – Function of one variable (first argument of f) with N free parameters.

  • x_err (array-like, optional) – Uncertainties associated with the independent variable. Default is None.

  • y_err (array-like, optional) – Uncertainties associated with the dependent variable. Default is None.

  • p0 (list or array-like of floats, optional) – Initial guess for the model parameters, in the form [a, …, z]. Default is None.

  • xlabel (str, optional) – Label (and units) for the independent variable.

  • ylabel (str, optional) – Label (and units) for the dependent variable.

  • xlim (tuple, optional) – Limits for the x-axis, in the form (xmin, xmax). The values should already be scaled with respect to xscale. If None or an empty tuple, the default limits will be automatically determined from the data.

  • ylim (tuple, optional) – Limits for the y-axis, in the form (ymin, ymax). The values should already be scaled with respect to yscale. If None or an empty tuple, the default limits will be automatically determined from the data.

  • showlegend (bool, optional) – If True, displays a legend with the reduced chi-square and p-value in the plot.

  • legendloc (str, optional) – Location of the legend in the plot (‘upper right’, ‘lower left’, ‘upper center’, etc.). Default is None.

  • bounds (2-tuple of array-like, optional) – Tuple ([lower_bounds], [upper_bounds]) specifying bounds for the parameters. Default is None.

  • confidencerange (bool, optional) – If True, displays the 1σ uncertainty band around the best-fit curve.

  • log (str, optional) – If set to ‘x’ or ‘y’, the corresponding axis is plotted on a logarithmic scale; if ‘xy’, both axes. Default is None.

  • maxfev (int, optional) – Maximum number of iterations allowed by curve_fit.

  • xscale (int, optional) – Scaling factor for the x-axis (e.g., xscale = -2 corresponds to 1e-2, to convert meters to centimeters).

  • yscale (int, optional) – Scaling factor for the y-axis.

  • confidence (int, optional) – Residual confidence interval to display, i.e., [-confidence, +confidence].

  • residuals (bool, optional) – If True, adds an upper panel showing fit residuals.

  • norm (bool, optional) – If True, residuals in the upper panel will be normalized.

  • verbose (bool, optional) – If True, prints a formatted summary report of the fit, including reduced chi-square, p-value, and percentage of residuals within ±2σ.

  • print_parameters (bool, optional) – If True, prints the best-fit parameters along with their standard uncertainties.

Returns:

  • popt (array-like) – Array of optimal parameters estimated from the fit.

  • perr (array-like) – Uncertainties on the optimal parameters (only if y_err is provided).

  • chi2_red (float) – Reduced chi-square value (χ²/dof).

  • p_value (float) – Fit p-value.

Notes

The values of xscale and yscale affect only the axis scaling in the plot and have no impact on the fitting computation itself. All model parameters are estimated using the original input data as provided.