random

Simulate a SimBiology model, adding variations by sampling the error model

Syntax

[ynew,parameterEstimates,randomEffects] = random(resultsObj)

[ynew,parameterEstimates] = random(resultsObj,data,dosing)

[ynew,parameterEstimates,randomEffects] = random(___,Name,Value)

Description

[ynew,parameterEstimates,randomEffects] = random(resultsObj) returns simulation results ynew with added noise using the error model information specified by the resultsObj.ErrorModelInfo property and estimated parameter values parameterEstimates which are returned by sbiofitmixed.

[ynew,parameterEstimates] = random(resultsObj,data,dosing) uses the specified data and dosing information.

[ynew,parameterEstimates,randomEffects] = random(___,Name,Value) uses additional options specified by one or more name-value arguments.

Note

The noise is only added to states that are responses which are the states included in the responseMap input argument when you called sbiofitmixed or the ResponseMap property of fitproblem.

Input Arguments

resultsObj — Estimation results

NLMEResults object

Estimation results, specified as an NLMEResults object, which contains estimation results returned by sbiofitmixed. It must be a scalar object.

The function calculates new parameter values using sbiosampleparameters with the covariate model returned by resultsObj.covariateModel, the fixed effect estimates (resultsObj.FixedEffects), and random effect covariance matrix (resultsObj.RandomEffectCovarianceMatrix). The function adds randomly sampled errors to the simulation results by calling sbiosampleerror using the error model and error model parameters from resultsObj.ErrorModelInfo.

data — Grouped data or output times

groupedData object | vector | cell array of vectors

Grouped data or output times, specified as a groupedData object, vector, or cell array of vectors of output times.

If it is a vector of time points, random simulates the model with new time points.

If it is a cell array of vectors of time points, random simulates the model n times using the output times from each time vector, where n is the length of data.

If the mixed-effects model from the original fit (using sbiofitmixed) uses a covariate model with covariates, the data must be a groupedData object containing covariate data with the same labels for the covariates (CovariateLabels property) specified in the original covariate model.

dosing — Dosing information

[] | {} | 2-D matrix of dose objects | cell vector of dose objects

Dosing information, specified as empty [] or {}, 2-D matrix or cell vector of SimBiology^® dose objects (ScheduleDose object or RepeatDose object).

If dosing is empty, no doses are applied during simulation, even if the model has active doses.

For a matrix of dose objects, it must have a single row or one row per group in the input data. If it has a single row, the same doses are applied to all groups during simulation. If it has multiple rows, each row is applied to a separate group, in the same order as the groups appear in the input data. Multiple columns are allowed so that you can apply multiple dose objects to each group.

For a cell vector of doses, it must have one element or one element per group in the input data. Each element must be [] or a vector of doses. Each element of the cell is applied to a separate group, in the same order as the groups appear in the input data.

In addition to manually constructing dose objects using sbiodose, if the input groupedData object has dosing information, you can use the createDoses method to construct doses.

Dose objects of the dosing input must be consistent with the original dosing data used with sbiofitmixed. The objects must have the same values for dose properties (such as TargetName) or must be parameterized in the same way as the original dosing data. For instance, suppose that the original dosing matrix has two columns of doses, where the doses in the first column target species x and those in the second column target species y. Then dosing must have doses in the first column targeting species x and those in the second column targeting species y. A parameterized dose example is as follows. Suppose that the Amount property of a dose used in the original sbiofitmixed call is parameterized to a model-scoped parameter 'A'. All doses for the corresponding group (column) in the dosing matrix input must have the Amount property parameterized to 'A'.

The number of rows in the dosing matrix or number of elements in the dosing cell vector and the number of groups or output time vectors in data determine the total number of simulation results in the output ynew. For details, see the table in the ynew argument description.

Note

If UnitConversion is turned on for the underlying SimBiology model that was used for fitting, dosing must specify valid amount and time units.

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.

Example: 'ParameterType','population' specifies to use population parameter estimates.

ParameterType — Parameter type

'individual' (default) | 'population'

Parameter type, specified as 'population' or 'individual' (default).

If value is 'individual', estimated parameter values and random effect values are resampled by calling sbiosampleparameters with the covariate model (specified by the data argument or returned by the covariateModel method of resultsObj), the fixed effect estimates (resultsObj.FixedEffects), and random effect covariance matrix (resultsObj.RandomEffectCovarianceMatrix). Parameter estimates and random effects are resampled for all groups. The function adds randomly sampled errors to the simulation results by calling sbiosampleerror using the error model and error model parameters from resultsObj.ErrorModelInfo.

If value is 'population', the method returns simulation results with noise using population parameter estimates. The estimated parameter values used in simulation are identical to resultsObj.PopulationParameterEstimates property unless you specify a new groupedData object data with new covariate data. In this case, the method will reevaluate the covariate model and this could change the parameter estimates.

Data Types: char | string

Variants — Variants to apply

[] | {} | 2-D matrix of variants | cell vector of variants

Variants to apply, specified as an empty array ([], {}), 2-D matrix or cell vector of variant objects.

If you do not specify this argument, the function has the following behavior depending on whether the second input argument (data) is specified also or not.

• If data is not specified, the function applies the group-specific variants from the original call to sbiofitmixed.

• If data is a vector or cell array of output times, the function does not apply the group-specific variants.

• If data is a groupedData object, the function applies variants only to groups whose group identifier matches a group identifier in the original training data that was used in the call to sbiofitmixed.

Note

• The baseline variants that were specified by the variants positional input argument in the original call to sbiofitmixed are always applied to the model, and they are applied before any group-specific variants.

• If there are no baseline variants, that is, you did not specify the variants input when calling sbiofitmixed, the function still applies the model active variants if there are any.

If the argument value is [] or {}, the function applies no group-specific variants.

If it is a matrix of variants, it must have either one row or one row per group. Each row is applied to a separate group, in the same order as the groups appear in data or dosing. If it has a single row, the same variants are applied to all groups during simulation. If there are multiple columns, the variants are applied in order from the first column to the last.

If it is a cell vector of variant objects, the number of cells must be one or must match the number of groups in the input data. Each element must be [] or a vector of variants. If there is a single cell containing a vector of variants, they are applied to all simulations. If there are multiple cells, the variants in the ith cell are applied to the simulation of the ith group.

The function defines the number of groups by examining the data, and dosing input arguments.

• data can have 1 or N groups.

• If data and dosing arguments are not specified, then the default data and dosing are determined as follows:

  • For unpooled fits, they are the data and dosing for the single group associated with that fit results.

  • For all other fits, they are the entire set of data and dosing associated with the call to sbiofitmixed.

Output Arguments

ynew — Simulation results with noise

vector of SimData objects

Simulation results, returned as a vector of SimData objects. The states reported in ynew are the states included in the responseMap input argument of sbiofitmixed and any other states listed in the StatesToLog property of the runtime options (RuntimeOptions) of the SimBiology model.

The total number of simulation results in ynew depends on the number of groups or output time vectors in data and the number of rows in the dosing matrix.

Number of groups or output time vectors in data	Number of rows in the dosing matrix	Simulation results
1	0, that is, dosing is empty []	The total number of SimData objects in ynew is 1. No doses are applied during simulation.
1	1	The total number of SimData objects in ynew is 1. The given row of doses is applied during the simulation.
1	N	The total number of SimData objects in ynew is N. Each row of dosing is applied to each simulation.
N	0, that is, dosing is empty []	The total number of SimData objects in ynew is N. No doses are applied during simulation.
N	1	The total number of SimData objects in ynew is N. The same row of doses is applied to each simulation.
N	N	The total number of SimData objects in ynew is N. Each row of dosing is applied to a separate group, in the same order that groups appear in data.
M	N	The function throws an error when M ≠ N.

parameterEstimates — Estimated parameter values

table

Estimated parameter values, returned as a table.

If you specify the value argument as 'individual', these estimated values will differ from those values from the original fit since parameter values are recalculated using sbiosampleparameters.

If 'ParameterType' is 'population', the estimated parameter values are identical to resultsObj.PopulationParameterEstimates property unless you specify a new groupedData object data with new covariate data.

randomEffects — Random effect values

table

Random effect values, specified as a table.

Version History

Introduced in R2014a