random
Simulate a SimBiology model, adding variations by sampling the error model
Syntax
Description
[
returns simulation results ynew
,parameterEstimates
,randomEffects
] =
random(resultsObj
)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
.
[
uses the specified ynew
,parameterEstimates
] =
random(resultsObj
,data
,dosing
)data
and dosing
information.
[
uses additional options specified by one or more namevalue arguments.ynew
,parameterEstimates
,randomEffects
] =
random(___,Name,Value
)
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 mixedeffects 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
[]
 {}
 2D matrix of dose objects  cell vector of dose objects
Dosing information, specified as empty []
or {}
, 2D 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 modelscoped 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.
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue 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
[]
 {}
 2D matrix of variants  cell vector of variants
Variants to apply, specified as an empty array ([]
, {}
), 2D 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 groupspecific variants from the original call tosbiofitmixed
.If
data
is a vector or cell array of output times, the function does not apply the groupspecific variants.If
data
is agroupedData
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 tosbiofitmixed
.
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 groupspecific variants.If there are no baseline variants, that is, you did not specify the
variants
input when callingsbiofitmixed
, the function still applies the model active variants if there are any.
If the argument value is []
or {}
, the function applies no groupspecific 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 have1
or N groups.If
data
anddosing
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 


 The total number of No doses are applied during simulation. 

 The total number of The given row of doses is applied during the simulation. 
 N  The total number of Each row of 
N 
 The total number of No doses are applied during simulation. 
N 
 The total number of The same row of doses is applied to each simulation. 
N  N  The total number of Each row of 
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
See Also
NLMEResults object
 sbiofitmixed
 sbiosampleparameters
 sbiosampleerror
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)