Main Content

sbionlinfit

Perform nonlinear least-squares regression using SimBiology models (requires Statistics and Machine Learning Toolbox software)

sbionlinfit will be removed in a future release. Use sbiofit instead.

Syntax

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, InitEstimates)
results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, InitEstimates, Name,Value)
results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, InitEstimates, optionStruct)
[results, SimDataI] = sbionlinfit(...)

Description

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, InitEstimates) performs least-squares regression using the SimBiology® model, modelObj, and returns estimated results in the results structure.

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, InitEstimates, Name,Value) performs least-squares regression, with additional options specified by one or more Name,Value pair arguments.

Following is an alternative to the previous syntax:

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, InitEstimates, optionStruct) specifies optionStruct, a structure containing fields and values used by the options input structure to the nlinfit (Statistics and Machine Learning Toolbox) function.

[results, SimDataI] = sbionlinfit(...) returns simulations of the SimBiology model, modelObj, using the estimated values of the parameters.

Input Arguments

modelObj

SimBiology model object used to fit observed data.

Note

If using a model object containing active doses (that is, containing dose objects created using the adddose method, and specified as active using the Active property of the dose object), be aware that these active doses are ignored by the sbionlinfit function.

pkModelMapObject

PKModelMap object that defines the roles of the model components in the estimation. For details, see PKModelMap object.

Note

If using a PKModelMap object that specifies multiple doses, ensure each element in the Dosed property is unique.

pkDataObj

PKData object that defines the data to use in fitting, and the roles of the data columns used for estimation. For details, see PKData object.

Note

For each subset of data belonging to a single group (as defined in the data column specified by the GroupLabel property), the software allows multiple observations made at the same time. If this is true for your data, be aware that:

  • These data points are not averaged, but fitted individually.

  • Different numbers of observations at different times cause some time points to be weighted more.

InitEstimates

Vector of initial parameter estimates for each parameter estimated in pkModelMapObject.Estimated. The length of InitEstimates must equal at least the length of pkmodelMapObject.Estimated. The elements of InitEstimates are transformed as specified by the ParamTransform name-value pair argument.

optionStruct

Structure containing fields and values used by the options input structure to the nlinfit (Statistics and Machine Learning Toolbox) function. The structure can also use the name-value pairs listed below as fields and values. Defaults for optionStruct are the same as for the options input structure to nlinfit, except for:

  • DerivStep — Default is the lesser of 1e-4, or the value of the SolverOptions.RelativeTolerance property of the configuration set associated with modelObj, with a minimum of eps^(1/3).

  • FunValCheck — Default is off.

If you have Parallel Computing Toolbox™, you can enable parallel computing for faster data fitting by setting the name-value pair argument 'UseParallel' to true in the statset options structure as follows:

parpool; % Open a parpool for parallel computing
opt = statset(...,'UseParallel',true); % Enable parallel computing
results = sbionlinfit(...,opt); % Perform data fitting

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

The Name,Value arguments are the same as the fields and values in the options structure accepted by nlinfit. For a complete list, see the options input argument in the nlinfit (Statistics and Machine Learning Toolbox) reference page in the Statistics and Machine Learning Toolbox™ documentation. The defaults for Name,Value arguments are the same as for the options structure accepted by nlinfit, except for:

  • DerivStep — Default is the lesser of 1e-4, or the value of the SolverOptions.RelativeTolerance property of the configuration set associated with modelObj, with a minimum of eps^(1/3).

  • FunValCheck — Default is off.

Following are additional Name,Value arguments that you can use with sbionlinfit.

ParamTransform

Vector of integers specifying a transformation function for each estimated parameter. The transformation function, f, takes estimate as an input and returns beta:

beta = f(estimate)

Each element in the vector must be one of these integers specifying the transformation for the corresponding value of estimate:

  • 0beta = estimate

  • 1beta = log(estimate) (default)

  • 2beta = probit(estimate)

  • 3beta = logit(estimate)

ErrorModel

Character vector specifying the form of the error term. Default is 'constant'. Each model defines the error using a standard normal (Gaussian) variable e, the function value f, and one or two parameters a and b. Choices are:

  • 'constant': y = f + a*e

  • 'proportional': y = f + b*abs(f)*e

  • 'combined': y = f + (a+b*abs(f))*e

  • 'exponential': y = f*exp(a*e), or equivalently log(y) = log(f) + a*e

If you specify an error model, the results output argument includes an errorparam property, which has the value:

  • a for 'constant' and 'exponential'

  • b for 'proportional'

  • [a b] for 'combined'

Note

If you specify an error model, you cannot specify weights.

Weights

Either of the following:

  • A matrix of real positive weights, where the number of columns corresponds to the number of responses. That is, the number of columns must equal the number of entries in the DependentVarLabel property of pkDataObj. The number of rows in the matrix must equal the number of rows in the data set.

  • A function handle that accepts a vector of predicted response values and returns a vector of real positive weights.

    Note

    If using a function handle, the weights must be a function of the response (dependent variable).

Default is no weights. If you specify weights, you cannot specify an error model.

Pooled

Logical specifying whether sbionlinfit does fitting for each individual (false) or if it pools all individual data and does one fit (true). If set to true, sbionlinfit uses the same model parameters for each dose level.

Default: false

Output Arguments

results

1-by-N array of objects, where N is the number of groups in pkDataObj. There is one object per group, and each object contains these properties:

  • ParameterEstimates — A dataset (Statistics and Machine Learning Toolbox) array containing fitted coefficients and their standard errors.

  • CovarianceMatrix — Estimated covariance matrix for the fitted coefficients.

  • beta — Vector of scalars specifying the fitted coefficients in transformed space.

  • R — Vector of scalars specifying the residual values, where R(i,j) is the residual for the ith time point and the jth response in the group of data. If your model incudes:

    • A single response, then R is a column vector of residual values associated with time points in the group of data.

    • Multiple responses, then R is a matrix of residual values associated with time points in the group of data, for each response.

  • J — Matrix specifying the Jacobian of the model, with respect to an estimated parameter, that is

    J(i,j,k)=ykβj|ti

    where ti is the ith time point, βj is the jth estimated parameter in the transformed space, and yk is the kth response in the group of data.

    If your model incudes:

    • A single response, then J is a matrix of Jacobian values associated with time points in the group of data.

    • Multiple responses, then J is a 3-D array of Jacobian values associated with time points in the group of data, for each response.

  • COVB — Estimated covariance matrix for the transformed coefficients.

  • mse — Scalar specifying the estimate of the error of the variance term.

  • errorparam — Estimated parameters of the error model. This property is a scalar if you specify 'constant', 'exponential', or 'proportional' for the error model. This property is a two-element vector if you specify 'combined' for the error model. This property is an empty array if you specify weights using the 'Weights' name-value pair argument.

SimDataI

SimData object containing data from simulating the model using estimated parameter values for individuals. This object includes observed states and logged states.

Version History

Introduced in R2009a