createVariants

Create variant objects from groupedData object

Since R2021b

Syntax

variants = createVariants(grpData,variableNames)

variants = createVariants(grpData,variableNames,groups)

variants = createVariants(___,Name=Value)

Description

variants = createVariants(grpData,variableNames) creates a column vector of variant objects for each group in grpData using data variables variableNames.

variants = createVariants(grpData,variableNames,groups) creates a vector of variant objects for the specified groups.

variants = createVariants(___,Name=Value) uses additional options specified by one or more name-value arguments.

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:

• 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
1 1 1	0 1 2	NaN NaN 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.
2 2 2	0 1 2	A NaN NaN	A The software uses the value A to create a group variant.
3 3 3	0 1 2	A A A	A
4 4 4	0 1 2	NaN A NaN	A
5 5 5	100 200 300	A NaN NaN	A
6 6 6	0 1 2	A B NaN	A

Invalid Setups for Group-Specific Variants

Group	Time	Variable	Group Variant Value
1 1 1	100 200 300	A B NaN	The software throws an error because you must specify a value at time = 0 if there are multiple distinct variable values.
2 2 2	0 1 2	NaN A B	The software throws an error because you must specify a value at time = 0 if there are multiple distinct variable values.

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