sbionlinfit

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`: `0` – `beta = estimate` `1` – `beta = log(estimate)` (default) `2` – `beta = probit(estimate)` `3` – `beta = 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 + ae `'proportional'`: y = f + babs(f)e `'combined'`: y = f + (a+babs(f))e `'exponential'`: y = fexp(ae), or equivalently log(y) = log(f) + ae 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 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) = {\frac{\partial y_{k}}{\partial β_{j}} |}_{t_{i}}$
where t_i is the ith time point, β_j is the jth estimated parameter in the transformed space, and y_k 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