Documentation

# 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` 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` 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 Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

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` 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 + 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` 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\left(i,j,k\right)={\frac{\partial {y}_{k}}{\partial {\beta }_{j}}|}_{{t}_{i}}$`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.

Get trial now