msl.nlf.datatypes module

Various data classes and enums.

class msl.nlf.datatypes.Correlation(path, coefficients)

Bases: object

Information about correlation coefficients.

Parameters:
coefficients: ndarray[float]

The correlation coefficients.

path: str

The path to the correlation file.

class msl.nlf.datatypes.Correlations(data, is_correlated)

Bases: object

Information about the correlations for a fit model.

Parameters:
data: list[Correlation]

A list of Correlation objects.

is_correlated: ndarray[bool]

Indicates which variables are correlated. The index 0 corresponds to the y-variable, the index 1 to x1, 2 to x2, etc.

class msl.nlf.datatypes.FitMethod(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Fitting methods.

Least squares (LS) minimises the sum of the squares of the vertical distances between each point and the fitted curve. The algorithms implemented for Levenberg Marquardt, Amoeba and Powell are described in Numerical Recipes.

Minimum distance (MD) minimises the sum of the distances (in two dimensions) between each point and the fitted curve. This type of fit is not available when data is correlated nor is it available when there is more than one independent variable (stimulus).

MiniMax (MM) minimises the value of the maximum absolute y-residual. This type of fit is not available when data is correlated.

AMOEBA_LS = 'Amoeba least squares'
AMOEBA_MD = 'Amoeba minimum distance'
AMOEBA_MM = 'Amoeba minimax'
LM = 'Levenberg-Marquardt'
POWELL_LS = 'Powell least squares'
POWELL_MD = 'Powell minimum distance'
POWELL_MM = 'Powell minimax'
class msl.nlf.datatypes.Input(absolute_residuals, correlated, correlations, delta, equation, fit_method, max_iterations, params, residual_type, second_derivs_B, second_derivs_H, tolerance, ux, uy, uy_weights_only, weighted, x, y)

Bases: object

The input data to a fit model.

Parameters:
absolute_residuals: bool

Whether absolute residuals or relative residuals are used to evaluate the eof.

correlated: bool

Whether correlations are applied in the fitting process.

correlations: Correlations

The information about the correlation coefficients.

delta: float

Only used for Amoeba fitting.

equation: str

The equation of the fit model.

fit_method: FitMethod

The method that is used for the fit.

max_iterations: int

The maximum number of fit iterations allowed.

params: InputParameters

The input parameters to the fit model.

residual_type: ResidualType

Residual Type that is used to evaluate the eof.

second_derivs_B: bool

Whether the second derivatives in the B matrix are included in the propagation of uncertainty calculations.

second_derivs_H: bool

Whether the second derivatives in the curvature matrix, H (Hessian), are included in the propagation of uncertainty calculations.

tolerance: float

The tolerance value to stop the fitting process.

ux: ndarray[float]

Standard uncertainties in the x (stimulus) data.

uy: ndarray[float]

Standard uncertainties in the y (response) data.

uy_weights_only: bool

Whether the y uncertainties only or a combination of the x and y uncertainties are used to calculate the weights for a weighted fit.

weighted: bool

Whether to include the standard uncertainties in the fitting process to perform a weighted fit.

x: ndarray[float]

The independent variable(s) (stimulus) data.

y: ndarray[float]

The dependent variable (response) data.

class msl.nlf.datatypes.ResidualType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Residual Type that is used to evaluate the eof.

DX_X = 'dx v x'

Uncertainty in \(x\) versus \(x\).

DX_Y = 'dx v y'

Uncertainty in \(x\) versus \(y\).

DY_X = 'dy v x'

Uncertainty in \(y\) versus \(x\).

DY_Y = 'dy v y'

Uncertainty in \(y\) versus \(y\).

class msl.nlf.datatypes.Result(calls, chisq, correlation, covariance, dof, eof, iterations, params)

Bases: object

The result from a fit model.

Parameters:
calls: int

The number of calls to the DLL fit function.

chisq: float

The chi-squared value.

correlation: ndarray[float]

Parameter correlation coefficient matrix.

covariance: ndarray[float]

Parameter covariance matrix.

dof: float

The number of degrees of freedom that are retained.

If a fit is weighted or correlated, the degrees of freedom is infinity. Otherwise, the degrees of freedom is equal to the number of data points (observations) minus the number of fit parameters.

eof: float

The error-of-fit value (the standard deviation of the residuals).

iterations: int

The total number of fit iterations.

params: ResultParameters

The result parameters from the fit model.

to_ureal(*, with_future=False, label='future')

Convert the result to a correlated ensemble of uncertain real numbers.

Parameters:

  • with_future (bool) – Whether to include an uncertain real number in the ensemble that is a future indication in response to a given stimulus (a predicted future response). This reflects the variability of single indications as well as the underlying uncertainty in the fit parameters. The value of this future uncertain number is zero, and the uncertainty component is \(\sqrt{\frac{\chi^2}{dof}}\).

  • label (str) – The label to assign to the future uncertain number.

Returns:

A correlated ensemble of uncertain real numbers.

Return type:

list of UncertainReal

Examples

Suppose the sample data has a linear relationship

>>> x = [3, 7, 11, 15, 18, 27, 29, 30, 30, 31, 31, 32, 33, 33, 34, 36,
...      36, 36, 37, 38, 39, 39, 39, 40, 41, 42, 42, 43, 44, 45, 46, 47, 50]
>>> y = [5, 11, 21, 16, 16, 28, 27, 25, 35, 30, 40, 32, 34, 32, 34, 37,
...      38, 34, 36, 38, 37, 36, 45, 39, 41, 40, 44, 37, 44, 46, 46, 49, 51]

The intercept and slope are determined from a fit

>>> from msl.nlf import LinearModel
>>> with LinearModel() as model:
...    result = model.fit(x, y)

We can estimate the response to a particular stimulus, say \(x=21.5\)

>>> intercept, slope = result.to_ureal()
>>> intercept + 21.5*slope
ureal(23.257962225044...,0.82160705888850...,31.0)

or a single future indication in response to a given stimulus may also be of interest (again, at \(x=21.5\))

>>> intercept, slope, future = result.to_ureal(with_future=True)
>>> intercept + 21.5*slope + future
ureal(23.257962225044...,3.33240925795711...,31.0)

The value here is the same as above (because the stimulus is the same), but the uncertainty is much larger, reflecting the variability of single indications as well as the underlying uncertainty in the intercept and slope.