sbionlmefitsa

Syntax

results = sbionlmefitsa(modelObj, pkModelMapObject, pkDataObject, InitEstimates) results = sbionlmefitsa(modelObj, pkModelMapObject, pkDataObject, CovModelObj) results = sbionlmefitsa(..., Name,Value) results = sbionlmefitsa(..., optionStruct) [results, SimDataI, SimDataP] = sbionlmefitsa(...)

Description

results = sbionlmefitsa(modelObj, pkModelMapObject, pkDataObject, InitEstimates) performs estimations using the Stochastic Approximation Expectation-Maximization (SAEM) algorithm for fitting population data with the SimBiology^® model, modelObj, and returns the estimated results in the results structure.

results = sbionlmefitsa(modelObj, pkModelMapObject, pkDataObject, CovModelObj) specifies the relationship between parameters and covariates using CovModelObj, a CovariateModel object. The CovariateModel object also provides the parameter transformation.

results = sbionlmefitsa(..., Name,Value) performs estimations using the SAEM algorithm, with additional options specified by one or more Name,Value pair arguments.

Following is an alternative to the previous syntax:

results = sbionlmefitsa(..., optionStruct) specifies optionStruct, a structure containing fields and values, that are the name-value pair arguments accepted by nlmefitsa. The defaults for optionStruct are the same as the defaults for the name-value pair arguments used by nlmefitsa, with the exceptions explained in Input Arguments.

[results, SimDataI, SimDataP] = sbionlmefitsa(...) returns simulation data of the SimBiology model, modelObj, using the estimated values of the parameters.

Input Arguments

`modelObject`	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 `sbionlmefitsa` function.
`pkModelMapObject`	`PKModelMap` object that defines the roles of the model components used for 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.
`pkDataObject`	`PKData` object that defines the data to use in fitting and the roles of the columns used for estimation. `pkDataObject` must define target data for at least two groups. 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 estimates for the fixed effects. The first `P` elements of `InitEstimates` correspond to the fixed effects for each `P` element of `pkModelMapObject`.`Estimated`. Additional elements correspond to the fixed effects for covariate factors. The first `P` elements of `InitEstimates` are transformed as specified by the `ParamTransform` name-value pair argument (log transformed by default).
`CovModelObj`	`CovariateModel` object that defines the relationship between parameters and covariates. For details, see `CovariateModel`.
`optionStruct`	Structure containing fields and values that are name-value pair arguments accepted by the `nlmefitsa` function. The defaults for `optionStruct` are the same as the defaults for the arguments used by `nlmefitsa`, with the exceptions noted in Name-Value Arguments. 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 = sbionlmefitsa(...,'Options',opt); % Perform data fitting Tip SimBiology software includes the `sbiofitstatusplot` function, which you can specify in the `OutputFcn` field of the `Options` field. This function lets you monitor the status of 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 sbionlmefitsa function uses the name-value pair arguments supported by the nlmefitsa function.

These nlmefitsa name-value pair arguments are hard-coded in sbionlmefitsa, and therefore, you cannot set them:

If you provide a CovariateModel object as input to sbionlmefitsa, then these nlmefitsa name-value pairs are computed from the covariate model, and therefore, you cannot set them:

FEGroupDesign
ParamTransform
REParamsSelect

You can set all other nlmefitsa name-value pair arguments. For details on these arguments, see the nlmefitsa (Statistics and Machine Learning Toolbox) reference page.

Be aware that the defaults for these nlmefitsa name-value pair arguments differ when used by sbionlmefitsa:

`FEGroupDesign`	Numeric array specifying the design matrix for each group. Default: `repmat(eye(P),[1 1 nGroups])`, where `P` = the number of estimated parameters, and `nGroups` = the number of groups in the observed data.
`ParamTransform`	Vector of integers specifying how the parameters are distributed. Note Do not use the `ParamTransform` option to specify parameter transformations when providing a `CovariateModel` object to a fitting function. The `CovariateModel` object provides the parameter transformation. Default: Vector of ones, which specifies all parameters are log transformed.
`OptimFun`	Character vector specifying the optimization function used in maximizing the likelihood. Default: `fminunc`, if you have Optimization Toolbox™ installed. Otherwise, the default is `fminsearch`.
`Options`	Structure containing multiple fields, including `DerivStep`, a scalar or vector specifying the relative difference used in the finite difference gradient calculation, and `FunValCheck`, a logical specifying whether to check for invalid values, such as `NaN` or `Inf`, from `modelfun`. Default: The default for `DerivStep` 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)`. The default for `FunValCheck` is `off`.

Tip

SimBiology software includes the sbiofitstatusplot function, which you can specify in the OutputFcn field of the Options name-value pair input argument. This function lets you monitor the status of fitting.

Output Arguments

`results`	Structure containing these fields: `FixedEffects` — A `dataset` array containing estimated fixed effects, including standard errors. `RandomEffects` — A `dataset` array containing sampled random effects for each group in the observed data in `pkDataObject`. `IndividualParametereEstimates` — A `dataset` array containing estimated parameter values for individuals, including random effects. `PopulationParameterEstimates` — A `dataset` array containing estimated parameter values for the population, without random effects. `RandomEffectCovarianceMatrix` — A `dataset` array containing the estimated covariance matrix of the random effects. `EstimatedParameterNames` — Cell array of character vectors specifying names of the estimated parameters. `CovariateNames` — Cell array of character vectors specifying names of the covariates in `CovModelObj`. `FixedEffectsStruct` — Structure containing the values of the estimated fixed effects. `stats` — Structure containing information such as `AIC`, `BIC`, and weighted residuals. For details on the fields in this structure, see the `stats` structure in `nlmefitsa` (Statistics and Machine Learning Toolbox) in the Statistics and Machine Learning Toolbox™ documentation. However, the fields in the `stats` structure returned by `sbionlmefitsa` vary slightly from those returned by `nlmefitsa`, namely: `ires`, `pres`, `iwres`, `pwres`, and `cwres` each contain a matrix of raw or weighted residuals, with the number of columns equal to the number of responses in the model. The `stats` structure returned by `sbionlmefit` includes an additional field, `Observed`. This field contains a character vector or cell array of character vectors specifying the measured responses that correspond to the columns in the matrices of the `ires`, `pres`, `iwres`, `pwres`, and `cwres` fields. The `Observed` field is the same as the `Observed` property of the `PKModelMap` input argument.
`SimDataI`	`SimData object` containing data from simulating the model using the estimated parameter values for individuals. This object includes observed states and logged states.
`SimDataP`	`SimData object` containing data from simulating the model using the estimated parameter values for the population. This object includes observed states and logged states.

Version History

Introduced in R2010a