sbionlmefit

Estimate nonlinear mixed effects using SimBiology models (requires Statistics and Machine Learning Toolbox software)

sbionlmefit will be removed in a future release. Use sbiofitmixed instead.

Syntax

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


Description

results = sbionlmefit(modelObj, pkModelMapObject, pkDataObject, InitEstimates) performs nonlinear mixed-effects estimation using the SimBiology^® model, modelObj, and returns estimated results in the results structure.

results = sbionlmefit(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 = sbionlmefit(..., Name,Value) performs nonlinear mixed-effects estimation, with additional options specified by one or more Name,Value pair arguments.

Following is an alternative to the previous syntax:

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

[results, SimDataI, SimDataP] = sbionlmefit(...) 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 sbionlmefit 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 pairs (log transformed by default).
CovModelObj	CovariateModel object that defines the relationship between parameters and covariates. For details, see CovariateModel object. Tip To simultaneously fit data from multiple dose levels, omit the random effect (eta) from the expressions in the CovariateModel object.
optionStruct	Structure containing fields and values that are the name-value pairs accepted by the nlmefit function. The defaults for optionStruct are the same as the defaults for the arguments used by nlmefit, with the exceptions noted in Name-Value Pair 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 = sbionlmefit(...,'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. Tip To simultaneously fit data from multiple dose levels, use the InitEstimates input argument and set the value of the REParamsSelect field to a 1-by-n logical vector, with all entries set to false, where n equals the number of fixed effects.

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 sbionlmefit function uses the name-value pair arguments supported by the nlmefit function.

These nlmefit name-value pairs are hard-coded in sbionlmefit, and therefore, you cannot set them:

• FEParamsSelect

• FEConstDesign

• FEGroupDesign

• FEObsDesign

• REConstDesign

• REGroupDesign

• REObsDesign

• Vectorization

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

• FEGroupDesign

• ParamTransform

• REParamsSelect

You can set all other nlmefit name-value pairs. For details, see the nlmefit (Statistics and Machine Learning Toolbox) reference page.

Be aware that the defaults for these nlmefit name-value pairs differ when used by sbionlmefit:

'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.

Tip

To simultaneously fit data from multiple dose levels, use the InitEstimates input argument and set the REParamsSelect name-value pair input argument to a 1-by-n logical vector, with all entries set to false, where n equals the number of fixed effects.

Output Arguments

results	Structure containing these fields: FixedEffects — A dataset (Statistics and Machine Learning Toolbox) 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 nlmefit (Statistics and Machine Learning Toolbox) in the Statistics and Machine Learning Toolbox™ documentation. However, the fields in the stats structure returned by sbionlmefit vary slightly from those returned by nlmefit, 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.