SimBiology.Variant

Store alternate component values

Description

The SimBiology.Variant object stores the names and values of model components and allows you to use the values stored in a variant object as the alternate value to be applied during a simulation. You can store values for species InitialAmount, parameter Value, and compartment Capacity in a variant object. Simulating using a variant does not alter the model component values. The values specified in the variant temporarily apply during simulation.

Using one or more variant objects associated with a model allows you to evaluate model behavior during simulation, with different values for the various model components without having to search and replace these values, or having to create additional models with these values. If you determine that the values in a variant object accurately define your model, you can permanently replace the values in your model with the values stored in the variant object, using the commit function.

To use a variant in a simulation you must add the variant object to the model object and set the Active property of the variant to true. Set the Active property to true if you always want the variant to be applied before simulating the model. You can also enter the variant object as an argument to sbiosimulate; this applies the variant only for the current simulation and supersedes any active variant objects on the model.

When there are multiple active variant objects on a model, if there are duplicate specifications for a property's value, the last occurrence for the property value in the array of variants, is used during simulation. You can find out which variant is applied last by looking at the indices of the variant objects stored on the model. Similarly, in the Content property, if there are duplicate specifications for a property's value, the last occurrence for the property in the Content property, is used during simulation.

Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands.

The SimBiology Model Builder app also enables you to add variants to your model and edit them. For an example, see Represent Biological Variability Using Variants.

Creation

Use sbiovariant to create a SimBiology.Variant object. Use addvariant (model) to add a SimBiology.Variant object to a SimBiology model.

Properties

Active — Flag to apply model component values stored in variant object during simulation

false or 0 (default) | true or 1

Flag to apply the model component values stored in variant object during simulation, specified as a numeric or logical 1 (true) or 0 (false).

Data Types: double | logical

Content — Contents of variant object

[] (default) | cell array

Contents of the variant object, specified as a cell array.

The Content property contains the data for the variant object. You can store values for species InitialAmount, parameter Value, and compartment Capacity, in a variant object.

Content is a cell array of cell arrays, where each cell array contains information on the component type, component name, property name, and property value. A valid cell array has the form of {'Type','Name','PropertyName',PropertyValue}. If a variant has no data, the Content property is set to []. For a parameter, if its scope is the model, specify the parameter name. If its scope is a reaction, qualify the parameter name with the reaction name, such as "reaction1.k", where k is a reaction-scoped parameter of reaction1. For details, see addcontent (variant).

Example: {{'species','A','InitialAmount',5},{'species','B','InitialAmount',10}}

Data Types: cell

Name — SimBiology.Variant object name

character vector | string

SimBiology.Variant object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology^® components, see Guidelines for Naming Model Components.

Data Types: char | string

Notes — Additional information

empty character array (default) | character vector | string

Additional information that you can add for SimBiology.Variant, specified as a character vector or string.

Data Types: char | string

Parent — Parent object

SimBiology.Model object

This property is read-only.

Parent object, specified as a SimBiology.Model object.

Tag — Object label

empty character array (default) | character vector | string

Object label, specified as a character vector or string.

Tip

Use this property to group objects and then use sbioselect to retrieve. For example, use the Tag property of reaction objects to group synthesis or degradation reactions. You can then retrieve all synthesis reactions using sbioselect. Similarly, for species objects you can enter and store classification information, for example, membrane protein, transcription factor, enzyme classifications, or whether a species is an independent variable. You can also enter the full form of the name of the species.

Data Types: char | string

Type — Object type

'variant' (default)

This property is read-only.

Object type, specified as 'variant'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

UserData — Data to associate with object

scalar | vector | string | ...

Data to associate with the object, specified as a numeric scalar, vector, string, or any other MATLAB data type.

The object does not use this data directly, but you can access it using dot notation or get.

Object Functions

addcontent (variant)	Append content to variant object
commit (variant)	Commit variant contents to model
copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
rename	Rename SimBiology model component and update expressions
rmcontent (variant)	Remove contents from variant object
set	Set SimBiology object properties
verify (model, variant)	Validate and verify SimBiology model

Examples

Add Contents to SimBiology Variant

Create a model containing three species in one compartment.

modelObj = sbiomodel('mymodel');
compObj = addcompartment(modelObj,'comp1');
A = addspecies(compObj,'A');
B = addspecies(compObj,'B');
C = addspecies(compObj,'C');

Add a variant object that varies the species InitialAmount property.

variantObj = addvariant(modelObj,'v1');
addcontent(variantObj,{{'species','A','InitialAmount', 5}, ...
{'species','B','InitialAmount',10}})

ans = 
   SimBiology Variant - v1 (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 species      A                 InitialAmount       5.0
   2                 species      B                 InitialAmount       10.0

Add another species data to the Content property.

addcontent(variantObj,{'species','C','InitialAmount',15})

ans = 
   SimBiology Variant - v1 (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 species      A                 InitialAmount       5.0
   2                 species      B                 InitialAmount       10.0
   3                 species      C                 InitialAmount       15.0

Remove a species from the Content property.

rmcontent(variantObj,3)

ans = 
   SimBiology Variant - v1 (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 species      A                 InitialAmount       5.0
   2                 species      B                 InitialAmount       10.0

Replace the data in the Content property.

variantObj.Content = {'species','C','InitialAmount',15}

variantObj = 
   SimBiology Variant - v1 (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 species      C                 InitialAmount       15.0

Simulate Wild type and Mutant Strains of G Protein Cycle

This example shows how to create and apply a variant to the G protein model of a wild-type strain. The variant represents a parameter value for the G protein model of a mutant strain. Thus, when you simulate the model without applying the variant, you see results for the wild type strain, and when you simulate the model with the variant, you see results for the mutant strain.

The value of the parameter kGd is 0.11 for the wild-type strain and 0.004 for the mutant strain. To represent the mutant strain, you will store an alternate value of 0.004 for the kGd parameter in a variant object, and apply this variant when simulating the model.

Load the gprotein.sbproj project, which includes the variable m1, a SimBiology.Model object.

sbioloadproject gprotein

You can create a variant of the original model by specifying a different parameter value for the kGd parameter of the model. First, add a variant to the m1 model object.

v1 = addvariant(m1,'mutant_strain');

Next, add a parameter kGd with a value of 0.004 to the variant object v1.

addcontent(v1,{'parameter','kGd','Value',0.004});

Simulate the wild type model.

[t,x,names] = sbiosimulate(m1);

Simulate the mutant strain model by applying the variant.

[tV,xV,names] = sbiosimulate(m1,v1);

Plot and compare the simulated results.

subplot(1,2,1)
plot(t,x);
legend(names);
xlabel('Time');
ylabel('Amount');
title('Wild Type');

subplot(1,2,2)
plot(tV,xV);
legend(names);
xlabel('Time');
ylabel('Amount');
title('Mutant Strain');

Simulate Model of Glucose-Insulin Response with Different Initial Conditions

This example shows how to simulate the glucose-insulin responses for the normal and diabetic subjects.

Load the model of glucose-insulin response. For details about the model, see the Background section in Simulate the Glucose-Insulin Response.

sbioloadproject('insulindemo', 'm1')

The model contains different initial conditions stored in various variants.

variants = getvariant(m1);

Get the initial conditions for the type 2 diabetic patient.

type2 = variants(1)

type2 = 
   SimBiology Variant - Type 2 diabetic (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 parameter    Plasma Volume ... Value               1.49
   2                 parameter    k1                Value               .042
   3                 parameter    k2                Value               .071
   4                 parameter    Plasma Volume ... Value               .04
   5                 parameter    m1                Value               .379
   6                 parameter    m2                Value               .673
   7                 parameter    m4                Value               .269
   8                 parameter    m5                Value               .0526
   9                 parameter    m6                Value               .8118
   10                parameter    Hepatic Extrac... Value               .6
   11                parameter    kmax              Value               .0465
   12                parameter    kmin              Value               .0076
   13                parameter    kabs              Value               .023
   14                parameter    kgri              Value               .0465
   15                parameter    f                 Value               .9
   16                parameter    a                 Value               6e-05
   17                parameter    b                 Value               .68
   18                parameter    c                 Value               .00023
   19                parameter    d                 Value               .09
   20                parameter    kp1               Value               3.09
   21                parameter    kp2               Value               .0007
   22                parameter    kp3               Value               .005
   23                parameter    kp4               Value               .0786
   24                parameter    ki                Value               .0066
   25                parameter    [Ins Ind Glu U... Value               1.0
   26                parameter    Vm0               Value               4.65
   27                parameter    Vmx               Value               .034
   28                parameter    Km                Value               466.21
   29                parameter    p2U               Value               .084
   30                parameter    K                 Value               .99
   31                parameter    alpha             Value               .013
   32                parameter    beta              Value               .05
   33                parameter    gamma             Value               .5
   34                parameter    ke1               Value               .0007
   35                parameter    ke2               Value               269.0
   36                parameter    Basal Plasma G... Value               164.18
   37                parameter    Basal Plasma I... Value               54.81

Suppress an informational warning that is issued during simulations.

warnSettings = warning('off','SimBiology:DimAnalysisNotDone_MatlabFcn_Dimensionless');

Create SimFunction objects to simulate the glucose-insulin response for the normal and diabetic subjects.

• Specify an empty array {} for the second input argument to denote that the model will be simulated using the base parameter values (that is, no parameter scanning will be performed).

• Specify the plasma glucose and insulin concentrations as responses (outputs of the function to be plotted).

• Specify the species Dose as the dosed species. This species represents the initial concentration of glucose at the start of the simulation.

normSim = createSimFunction(m1,{},...
             {'[Plasma Glu Conc]','[Plasma Ins Conc]'},'Dose')

normSim = 
SimFunction

Parameters:

    Name    Value    Type    Units
    ____    _____    ____    _____


Observables: 

            Name                Type                 Units         
    _____________________    ___________    _______________________

    {'[Plasma Glu Conc]'}    {'species'}    {'milligram/deciliter'}
    {'[Plasma Ins Conc]'}    {'species'}    {'picomole/liter'     }

Dosed: 

    TargetName       TargetDimension   
    __________    _____________________

     {'Dose'}     {'Mass (e.g., gram)'}


TimeUnits: hour

For the diabetic patient, specify the initial conditions using the variant type2.

diabSim = createSimFunction(m1,{},...
             {'[Plasma Glu Conc]','[Plasma Ins Conc]'},'Dose',type2)

diabSim = 
SimFunction

Parameters:

    Name    Value    Type    Units
    ____    _____    ____    _____


Observables: 

            Name                Type                 Units         
    _____________________    ___________    _______________________

    {'[Plasma Glu Conc]'}    {'species'}    {'milligram/deciliter'}
    {'[Plasma Ins Conc]'}    {'species'}    {'picomole/liter'     }

Dosed: 

    TargetName       TargetDimension   
    __________    _____________________

     {'Dose'}     {'Mass (e.g., gram)'}


TimeUnits: hour

Select a dose that represents a single meal of 78 grams of glucose at the start of the simulation.

singleMeal = sbioselect(m1,'Name','Single Meal');

Convert the dosing information to the table format.

mealTable  = getTable(singleMeal);

Simulate the glucose-insulin response for a normal subject for 24 hours.

sbioplot(normSim([],24,mealTable));

Simulate the glucose-insulin response for a diabetic subject for 24 hours.

sbioplot(diabSim([],24,mealTable));

Perform a Scan Using Variants

Suppose you want to perform a parameter scan using an array of variants that contain different initial conditions for different insulin impairments. For example, the model m1 has variants that correspond to the low insulin sensitivity and high insulin sensitivity. You can simulate the model for both conditions via a single call to the SimFunction object.

Select the variants to scan.

varToScan = sbioselect(m1,'Name',...
                    {'Low insulin sensitivity','High insulin sensitivity'});

Check which model parameters are being stored in each variant.

varToScan(1)

ans = 
   SimBiology Variant - Low insulin sensitivity (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 parameter    Vmx               Value               .0235
   2                 parameter    kp3               Value               .0045

varToScan(2)

ans = 
   SimBiology Variant - High insulin sensitivity (inactive)

   ContentIndex:     Type:        Name:             Property:           Value:
   1                 parameter    Vmx               Value               .094
   2                 parameter    kp3               Value               .018

Both variants store alternate values for Vmx and kp3 parameters. You need to specify them as input parameters when you create a SimFunction object.

Create a SimFunction object to scan the variants.

variantScan = createSimFunction(m1,{'Vmx','kp3'},...
          {'[Plasma Glu Conc]','[Plasma Ins Conc]'},'Dose');

Simulate the model and plot the results. Run 1 include simulation results for the low insulin sensitivity and Run 2 for the high insulin sensitivity.

sbioplot(variantScan(varToScan,24,mealTable));

Low insulin sensitivity lead to increased and prolonged plasma glucose concentration.

Restore warning settings.

warning(warnSettings);

Version History

Introduced in R2008a

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.

R2016b: Active property will be removed

The Active property of the object will be removed in a future release.

Explicitly specify the corresponding variant object as an input argument when you run sbiosimulate.