Main Content

random(NLMEResults)

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(_,'ParameterType',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(_,'ParameterType',value) adds noise to simulation results that are simulated using either individual or population parameter estimates. The two choices for value are 'population' or 'individual' (default).

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.

Input Arguments

collapse all

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

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.

For both cases, new parameter values are calculated using sbiosampleparameters with the covariate model returned by resultsObj.covariateModel, the fixed effect estimates (resultsObj.FixedEffects), and random effect covariance matrix (resultsObj.RandomEffectCovarianceMatrix).

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 information, specified as an empty array [] or 2-D matrix of SimBiology dose objects (ScheduleDose object or RepeatDose object). If dosing is a matrix of dose objects, the matrix must contain default doses or be consistent with the original dosing data used with sbiofitmixed. That is, dose objects in dosing 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 first column targets species x and the second column targets species y. Then dosing must have doses in the first column targeting species x and doses in the second column targeting species y.

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

  • If not empty, the matrix 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. If some groups (or time vectors) require more doses than others, then fill in the matrix with default (dummy) doses.

  • Multiple columns are allowed so that you can apply multiple dose objects to each group or time vector. All doses in a column must be default doses or must reference the same components in the model (for instance, the doses must have the same TargetName) and must have consistent parameterized properties as in the original dosing data used with sbiofitmixed. For example, if 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 dosing must have the Amount property parameterized to 'A'.

  • A default dose has default values for all properties, except for the Name property. Create a default dose as follows.

    d1 = sbiodose('d1');

  • In addition to manually constructing dose objects using sbiodose, if the input data is a groupedData object and has dosing information, you can use the createDoses method to construct doses from it.

The number of rows in the dosing matrix 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.

Parameter type, specified as 'population' or 'individual' (default). If value is 'population', the method returns the simulation results with noise using the 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.

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.

Output Arguments

collapse all

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 dataNumber of rows in the dosing matrixSimulation 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.

NN

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.

MNThe function throws an error when MN.

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.

Random effect values, specified as a table.

Introduced in R2014a