deerlab.fit

fit(model_, y, *constants, par0=None, penalties=None, bootstrap=0, noiselvl=None, mask=None, weights=None, regparam='aic', reg='auto', regparamrange=None, bootcores=1, **kwargs)[source]

Fit the model(s) to the dataset(s)

Fit the input model to the data y via one of the three following approaches:

  • Non-linear least-squares

  • Regularized linear-least-squares

  • Separable non-linear least-squares

The most appropiate solver is chosen automatically based on the model structure.

Parameters:
modeldeerlab.Model

Model object.

yarray_like

Data to be fitted.

par0array_like, optional

Value at which to initialize the parameter at the start of a fit routine. Must be specified if not defined in the model. Otherwise, it overrides the definition in the model.

penalties: callable or list thereof, optional

Custom penalty function(s) to impose upon the solution. A single penalty must be specified as a callable function. Multiple penalties can be specified as a list of callable functons. Each function must take two inputs, a vector of non-linear parameters and a vector of linear parameters, and return a vector to be added to the residual vector (pen = fcn(pnonlin,plin)). The square of the penalty is computed internally.

bootstrapscalar, optional,

Bootstrap samples for uncertainty quantification. If bootstrap>0, the uncertainty quantification will be performed via the boostrapping method with based on the number of samples specified as the argument.

bootcoresscalar, optional

Number of CPU cores/processes for parallelization of the bootstrap uncertainty quantification. If cores=1 no parallel computing is used. If cores=-1 all available CPUs are used. The default is one core (no parallelization).

regboolean or string, optional

Determines the use of regularization on the solution of the linear problem.

  • 'auto' - Automatic decision based con the condition number of the non-linear model Amodel.

  • True - Forces regularization regardless of the condition number

  • False - Disables regularization regardless of the condition number

The default is 'auto'.

regparamstring or float scalar, optional

Method for the automatic selection of the optimal regularization parameter:

  • 'lr' - L-curve minimum-radius method (LR)

  • 'lc' - L-curve maximum-curvature method (LC)

  • 'cv' - Cross validation (CV)

  • 'gcv' - Generalized Cross Validation (GCV)

  • 'rgcv' - Robust Generalized Cross Validation (rGCV)

  • 'srgcv' - Strong Robust Generalized Cross Validation (srGCV)

  • 'aic' - Akaike information criterion (AIC)

  • 'bic' - Bayesian information criterion (BIC)

  • 'aicc' - Corrected Akaike information criterion (AICC)

  • 'rm' - Residual method (RM)

  • 'ee' - Extrapolated Error (EE)

  • 'ncp' - Normalized Cumulative Periodogram (NCP)

  • 'gml' - Generalized Maximum Likelihood (GML)

  • 'mcl' - Mallows’ C_L (MCL)

The regularization parameter can be manually specified by passing a scalar value instead of a string. The default 'aic'.

regparamrangearray_like, optional

Search range for the optimization of the regularization parameter. Must be specified as a list [regparam_lb, regparam_ub] with the lower/upper boundaries of the regularization parameter. The default range is [1e-8, 1e3].

regop2D array_like, optional

Regularization operator matrix, the default is the second-order differential operator.

alphareoptfloat scalar, optional

Relative parameter change threshold for reoptimizing the regularization parameter when using a selection method, the default is 1e-3.

nnlsSolverstring, optional

Solver used to solve a non-negative least-squares problem (if applicable):

  • 'qp' - Optimization of the NNLS problem using the quadprog package. Only Python <= 3.10.

  • 'cvx' - Optimization of the NNLS problem using the cvxopt package.

  • 'fnnls' - Optimization using the fast NNLS algorithm.

The default is 'cvx'.

nnlsSolver : string, optional Solver used to solve a non-negative least-squares problem (if applicable):

noiselvlarray_like, optional

Noise standard deviation of the input signal(s), if not specified it is estimated automatically.

maskarrau_like or list thereof, optional

Array (or list of arrays) containing boolean (True/False) values defining a mask over one or multiple datasets. All dataset point with enabled mask values (True) will be acoounted for during the fitting procedure. All disabled values (False) will not be inlcuded. This does not affect model evaluation and uncertainty propagation.

weightsarray_like, optional

Array of weighting coefficients for the individual signals in global fitting. If not specified all datasets are weighted inversely proportional to their noise levels.

multistartint scalar, optional

Number of starting points for global optimization, the default is 1.

xtolfloat scalar, optional

Tolerance for termination by the change of the independent variables. Default is 1e-8. The optimization process is stopped when norm(dx) < xtol * (xtol + norm(x)). If set to None, the termination by this condition is disabled.

ftolfloat scalar, optional

Tolerance for termination by the change of the cost function. Default is 1e-8. The optimization process is stopped when dF < ftol*F, and there was an adequate agreement between a local quadratic model and the true model in the last step. If set to None, the termination by this condition is disabled.

max_nfevfloat scalar, optional

Maximum number of function evaluations before the termination. the default is 1e8.

lin_maxiterfloat scalar, optional

Linear solver maximal number of iterations, the default is 1e4.

lin_tolfloat scalar, optional

Linear solver tolerance to decide when a value is defined as a zero, the default is 1e-15.

uqboolean, optional

Enable/disable the uncertainty quantification analysis. Enabled by default.

modeluqboolean, optional

Enable/disable the propagation of the parameter uncertainties to the model’s response (can be computationally costly). Disabled by default

verbosescalar integer, optional

Level of verbosity during the analysis:

Returns:
deerlab.FitResult with the following fields defined:
<parameter_name>deerlab.Parameter

Fitted value of the <parameter_name> model parameter.

<parameter_name>Uncertdeerlab.UQResult

Uncertainty quantification of the <parameter_name> model parameter.

paramndarray

Fitted parameter vector ordered according to the model parameter indices.

paramUncertdeerlab.UQResult

Uncertainty quantification of the parameter vector ordered according to the model parameter indices.

paramlistlist

List of the fitted parameter names ordered according to the model parameter indices.

modelndarray

Fitted model response.

regparamscalar

Regularization parameter value used for the regularization of the linear parameters.

penweightsscalar or list thereof

Penalty weight value(s) used for the penalties specified through penalties.

statsdict

Goodness of fit statistical estimators

  • stats['chi2red'] - Reduced chi^2 test

  • stats['r2'] - R^2 test

  • stats['rmsd'] - Root-mean squared deviation (RMSD)

  • stats['aic'] - Akaike information criterion

  • stats['aicc'] - Corrected Akaike information criterion

  • stats['bic'] - Bayesian information criterion

costfloat

Value of the cost function at the solution.

noiselvlndarray

Estimated or user-given noise standard deviations of the individual datasets.