createVariants
Syntax
Description
creates a column vector of variant objects for each group in variants
= createVariants(grpData
,variableNames
)grpData
using data variables variableNames
.
creates a vector of variant objects for the specified variants
= createVariants(grpData
,variableNames
,groups
)groups
.
uses additional options specified by one or more name-value arguments.variants
= createVariants(___,Name=Value
)
Examples
Import sample data. The data contain three groups (individuals) with some time course measurement data. The Cl_Central
and Central
columns represent group-specific variant values.
tbl = readtable('sample_data_variants_simbiology.xlsx')
tbl=16×6 table
Group Time CentralConc Dose1 Cl_Central Central
_____ ____ ___________ _____ __________ _______
1 0 83.378 100 0.65 0.96
1 0 85 NaN NaN NaN
1 1 31.019 NaN NaN NaN
1 4 6.4875 NaN NaN NaN
1 8 1.1631 NaN NaN NaN
1 36 0 NaN NaN NaN
2 0 49.992 100 0.55 0.67
2 1 25.276 NaN 0.55 0.67
2 4 7.1079 NaN 0.55 0.67
2 8 2.7109 NaN 0.55 0.67
2 36 0 NaN 0.55 0.67
3 0 NaN 100 0.78 NaN
3 1 26.269 NaN NaN NaN
3 4 14.365 NaN NaN NaN
3 8 7.3422 NaN NaN NaN
3 36 0.18685 NaN NaN NaN
Convert to a groupedData
object.
gdata = groupedData(tbl);
By default, the function uses the "Group" column as the group variable.
gdata.Properties.GroupVariableName
ans = 'Group'
Create a variant for each group for using the Cl_Central
and Central
variables from the data.
variants = createVariants(gdata,["Cl_Central","Central"])
variants = SimBiology Variant Array Index: Name: Active: 1 1 false 2 2 false 3 3 false
variants(1)
ans = SimBiology Variant - 1 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .65 2 parameter Central Value .96
variants(2)
ans = SimBiology Variant - 2 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .55 2 parameter Central Value .67
variants(3)
ans = SimBiology Variant - 3 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .78
Note that individual 3 has a variant value for Cl_Central
but not Central
. Hence the function created only one variant content, for Cl_Central
.
You can also specify which group to create variants for. For example, create variants for individuals 1 and 2 only.
variants = createVariants(gdata,["Cl_Central","Central"],["1","2"])
variants = SimBiology Variant Array Index: Name: Active: 1 1 false 2 2 false
variants(1)
ans = SimBiology Variant - 1 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .65 2 parameter Central Value .96
variants(2)
ans = SimBiology Variant - 2 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .55 2 parameter Central Value .67
By default, the function assigns the type as parameter for each variable. You can specify which type (species, parameter, or compartment) by using the Types
name-value argument. Specify Cl_Central
as a parameter and Central
as a compartment.
variants = createVariants(gdata,["Cl_Central","Central"],Types=["parameter","compartment"]); variants(1)
ans = SimBiology Variant - 1 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .65 2 compartment Central Value .96
variants(2)
ans = SimBiology Variant - 2 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .55 2 compartment Central Value .67
variants(3)
ans = SimBiology Variant - 3 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .78
If you know the name of model component that maps to each variable, you can use the component name to define the Name of each variant content. For example, map the data variables to the model components named "Clearance" and "Central".
variants = createVariants(gdata,["Cl_Central","Central"],Types=["parameter","compartment"],Names=["Clearance","Central"]); variants(1)
ans = SimBiology Variant - 1 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Clearance Value .65 2 compartment Central Value .96
variants(2)
ans = SimBiology Variant - 2 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Clearance Value .55 2 compartment Central Value .67
variants(3)
ans = SimBiology Variant - 3 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Clearance Value .78
If your data variables have the same names as the corresponding model components, you can use the model as the source and the function automatically does the mapping.
% Create a two-compartment model. pkmd = PKModelDesign; pkc1 = addCompartment(pkmd,'Central'); pkc1.DosingType = 'Bolus'; pkc1.EliminationType = 'linear-clearance'; pkc1.HasResponseVariable = true; pkc2 = addCompartment(pkmd,'Peripheral'); model = construct(pkmd); variants = createVariants(gdata,["Cl_Central","Central"],Model=model); variants(1)
ans = SimBiology Variant - 1 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .65 2 compartment Central Value .96
Alternatively, if you have the corresponding model component objects, you can use them as well to map to the data variables.
% Extract the parameter and compartment object. clearance = sbioselect(model,Name="Cl_Central"); centralVol = sbioselect(model,Name="Central"); % Map the data variables to these objects. variants = createVariants(gdata,["Cl_Central","Central"],Components=[clearance,centralVol])
variants = SimBiology Variant Array Index: Name: Active: 1 1 false 2 2 false 3 3 false
variants(1)
ans = SimBiology Variant - 1 (inactive) ContentIndex: Type: Name: Property: Value: 1 parameter Cl_Central Value .65 2 compartment Central Value .96
Input Arguments
Grouped data, specified as a groupedData
object.
grpData
.Properties.GroupVariableName
optionally identifies a grouping variable.
Names of data variables used to generate variants, specified as a character vector, string, string vector, or cell array of character vectors.
Each variable in variableNames
must be a numeric column vector
without Inf
values.
For each variable:
You can use NaN to indicate no value for a particular row.
If all values of a variable within a group are
NaN
, the software creates no entry in the variant content for the group. When you simulate a model with the variant, the software uses the associated model component value as the initial value for model simulation. For details on how the software determines the initial conditions, see Model Simulation.If different non-NaN values are present for a group, the value specified at time = 0 is used to create the group variant.
See the tables below for illustration of valid and invalid data set setups for specifying group-specific variants. The Group column contains grouping information, the Time column contains time values that are monotonically increasing, the Variable column contains values for a model component that you may want to create a variant for, and the Group Variant Value column contains the variant value that the software uses to create a variant for the corresponding group in preparation for simulation. A and B are distinct non-NaN numeric scalar values.
Valid Setups for Group-Specific Variants
Group | Time | Variable | Group Variant Value |
---|---|---|---|
|
|
| The software creates no entry in the variant content for the group. When you simulate a model with the variant, the software uses the associated model component value as the initial value for model simulation. |
|
|
| A The software uses the value A to create a group variant. |
|
|
| A |
|
|
| A |
|
|
| A |
|
|
| A |
Invalid Setups for Group-Specific Variants
Group | Time | Variable | Group Variant Value |
---|---|---|---|
|
|
| The software throws an error because you must specify a value at time = 0 if there are multiple distinct variable values. |
|
|
| The software throws an error because you must specify a value at time = 0 if there are multiple distinct variable values. |
Group names, specified as an empty vector []
, character vector,
string scalar, string vector, cell array of character vectors, or a vector of data types
that can be converted to a categorical vector. For a list of supported data types, see
categorical
.
Use []
to indicate the default behavior of including variants for
each group.
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.
Example: Types="compartment",Names="Central"
specifies the model
component type as compartment and its name as Central
.
Model component types used in the variants, specified as
"parameter"
, "species"
,
"compartment"
, string vector, or cell array of character vectors,
where each element must be one of these strings or character vectors.
If you specify only one component type, the function applies it to all variant
content. If you specify more than one type, the number of types must match the number
of names in variableNames
.
You cannot specify this argument together with 'Components'
or
'Model'
.
Data Types: char
| string
| cell
Model component names used in the variants, specified as a character vector,
string scalar, string vector, or cell array of character vectors. If you do not
specify this argument or 'Components'
, by default, the function
uses the names from the variableName
input argument as the
component names.
You cannot specify this argument together with
'Components'
.
Data Types: char
| string
| cell
Model components used in the variants, specified as a vector of parameter,
species, or compartment objects. The number of components must match the number of
names in variableNames
. The types and names used in the variant
contents are the types and qualified names
of the specified components.
You cannot specify this argument together with
'Types'
,'Names'
, or
'Model'
.
SimBiology model used to identify the model components in the variants, specified as a model object.
When you have a name that matches different quantities, the software uses the following precedence rule to decide: species > compartment > parameter. For details, see Precedence Rules for Evaluating Quantity Names.
You cannot specify this argument together with 'Types'
or
'Components'
.
Flag to convert units of the data variable to the units specified for each model
component, specified as "auto"
, true
, or
false
. The variable units are defined in
grpData.Properties.VariableUnits
.
When the value is "auto"
, the function converts units for any
pair of variable and component that both specify nonempty units, which are consistent
with each other. Otherwise, the values in the data variables are used without unit
conversion.
When the value is true
, the function converts all values in the
data variables to the units of each component. You can set the value to
true
only if you have specified the model components using either
the Model
or Components
name-value
argument.
When the value is false
, the function uses the values in the
data variables without unit conversion.
Output Arguments
SimBiology variant objects, returned as a column vector of variant objects, with one
variant for each group in grpData
. If you do not specify the
groups
input, the order of returned variants follows the order of
groups in the input data. If you specify groups
, the order of
variants follows the order of specified groups.
Version History
Introduced in R2021b
See Also
Variant object
| table
| groupedData
| ScheduleDose object
| RepeatDose object
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)