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
Create Variants from Grouped Data
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
grpData
— Grouped data
groupedData
object
Grouped data, specified as a groupedData
object.
grpData
.Properties.GroupVariableName
optionally identifies a grouping variable.
variableNames
— Names of data variables
character vector | string | string vector | cell array of character vectors
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, the non-NaN values within a group can be repeated but they must
be identical. You can use NaN
to indicate no value for a particular
row. If all values of a variable within a group are NaN
, that
variable is not included in the group variant.
groups
— Group names
[]
| character vector | string scalar | string vector | cell array of character vectors | vector
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
.
Types
— Model component types
"parameter"
(default) | "species"
| "compartment"
| string vector | cell array of character vectors
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
Names
— Model component names
names from variableNames
input
argument (default) | character vector | string scalar | string vector | cell array of character vectors
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
Components
— Model components
vector of parameter, species, or compartment objects
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'
.
Model
— SimBiology model
model object
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'
.
UnitConversion
— Flag to convert units
"auto"
(default) | true
| false
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
variants
— SimBiology variant objects
column vector of variant objects
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)