SimBiology.Model

Model and component information

Description

The SimBiology.Model object represents a model, which is a collection of interrelated reactions and rules that transform, transport, and bind species. The model includes model components such as compartments, reactions, parameters, rules, and events. Each of the components is represented as a property of the model object. A model object also has a default configuration set object to define simulation settings. You can also add more configuration set objects to a model object.

The object properties define the characteristics of an object. Use the get and set commands to list object properties and change their values at the command line. You can interactively change object properties in SimBiology Model Builder.

You can retrieve SimBiology^® model objects from the SimBiology root object. A SimBiology model object has its Parent property set to the SimBiology root object. The root object contains a list of model objects that are accessible from the MATLAB^® command line and from the SimBiology apps. Because both the command line and the apps point to the same model object in the Root object, any changes you make to the model at the command line are reflected in the apps, and vice versa.

Creation

Use sbiomodel to create a SimBiology.Model object.

Properties

expand all

`Compartments` — Compartments in model
empty array (default) | array of `SimBiology.Compartment` objects

This property is read-only.

Compartments in the model, specified as an array of SimBiology.Compartment objects.

Use addcompartment to add a compartment to the model.

`Events` — Events in model
empty array (default) | array of `SimBiology.Event` objects

This property is read-only.

Events in the model, specified as an array of SimBiology.Event objects.

An event defines an action when a defined condition is met. For example, the quantity of a species may double when the quantity of species B is 100. An event is triggered when the conditions specified in the event are met by the model. For more information, see Events and Events in SimBiology Models.

Add an event to a Model object with the method addevent (model) method and remove an event with the delete method. See SimBiology.Event for more information.

You can view event object properties with the get command and modify the properties with the set command.

`Name` — Name of model
character vector | string scalar

Name of the model object, specified as a character vector or string scalar.

The Name property identifies a SimBiology object. Use the function sbioselect to find an object by its name.

For details about the constraints and reserved characters that you cannot use as the Name property, see Evaluation of Model Component Names in Expressions.

For more information on valid MATLAB variable names, see matlab.lang.makeValidName, matlab.lang.makeUniqueStrings, and isvarname.

Data Types: char | string

`Notes` — HTML text describing SimBiology object
empty character array (default) | character vector | string scalar

HTML text describing the SimBiology object, specified as a character vector or string scalar.

Data Types: char | string

`Observables` — Expressions for post-simulation calculations
empty array (default) | array of `SimBiology.Observable` objects

Since R2020a

This property is read-only.

Expressions for post-simulation calculations, specified as an SimBiology.Observable object.

You can add an observable object to a model object using addobservable.

`Parent` — Parent object
`SimBiology.Root` object

This property is read-only.

Parent object, specified as a SimBiology.Root object.

`Parameters` — Parameters in model
empty array (default) | array of `SimBiology.Parameter` objects

This property is read-only.

Parameters in the model, specified as an array of Parameter objects.

The scope of a parameter object is hierarchical and is defined by the parameter’s parent. If a parameter is defined with a kinetic law object as its parent, then only the kinetic law object can use the parameter. If a parameter object is defined with a model object as its parent, then components such as rules, events, and kinetic laws (reaction rate equations) can use the parameter.

You can add a parameter to a model object addparameter and delete it with the method delete.

`Reactions` — Reactions in model
empty array (default) | array of `SimBiology.Reaction` objects

Reactions in the model, specified as an array of SimBiology.Reaction objects.

A reaction object defines a chemical reaction that occurs between species. You can add a reaction to a model object with the method addreaction, and you can remove a reaction from the model object with the method delete.

`Rules` — Rules in model
empty array (default) | array of `SimBiology.Rule` objects

Rules in the model, specified as an array of Rule objects.

A rule is a mathematical expression that modifies a species amount or a parameter value. A rule defines how certain species and parameters should interact with one another. For example, a rule could state that the total number of species A and species B must be some value.

You can add a rule to a model object with the addrule method and remove the rule with the delete method. For more information, see Definitions and Evaluations of Rules in SimBiology Models.

`Species` — Species in `SimBiology.Model`
empty `SimBiology.Species` array (default) | array of `SimBiology.Species` objects

This property is read-only.

Species in the SimBiology.Model object, specified as an array of SimBiology.Species objects.

In the SimBiology.Model object, Species contains a flat list of all the species that exist within all the compartments in the model. You should always access a species through its compartment rather than the model object. Use the format compartmentName.speciesName, for example, nucleus.DNA. Another example of the syntax is modelObj.Compartments(2).Species(1). The Species property in the model object might not be available in a future version of the software.

Species are entities that take part in reactions. A species object is added to the Species property when a reaction is added to the model object with the method addreaction. A species object can also be added to the Species property with addspecies.

If you remove a reaction with delete, and a species is no longer being used by any of the remaining reactions, the species object is not removed from the Species property. You have to call delete on each species to remove it.

There are reserved characters that cannot be used in species object names. See the Name property for more information.

`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
`'sbiomodel'` (default)

This property is read-only.

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

Data Types: char

`UserData` — Data to associate with model 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

`addcompartment`	Create compartment object and add to model or compartment
`addconfigset (model)`	Create configuration set object and add to model object
`adddose`	Add dose object to model
`addevent (model)`	Add event object to model object
`addobservable`	Add observable object to SimBiology model
`addparameter`	Create parameter object and add to model or kinetic law object
`addreaction`	Create reaction object and add to model
`addrule`	Add rule object to model
`addspecies`	Create species object and add to model or compartment
`addvariant (model)`	Add variant to model
`copyobj`	Copy SimBiology object and its children
`createSimFunction`	Create `SimFunction` object
`delete`	Delete SimBiology object
`display`	Display summary of SimBiology object
`export (model)`	Export SimBiology models for deployment and standalone applications
`findUnusedComponents (model)`	Find unused species, parameters, and compartments in a model
`generateCode`	Generate MATLAB function to recreate SimBiology model
`get`	Get SimBiology object properties
`getadjacencymatrix (model)`	Get adjacency matrix from model object
`getconfigset (model)`	Get configuration set object from model object
`getdose (model)`	Return SimBiology dose object
`getequations`	Return system of equations for model object
`getstoichmatrix (model)`	Get stoichiometry matrix from model object
`getvariant (model)`	Get variant from model
`removeconfigset (model)`	Remove configuration set from model
`removedose (model)`	Remove dose object from model
`removevariant (model)`	Remove variant from model
`rename`	Rename SimBiology model component and update expressions
`reorder (model, compartment, kinetic law)`	Reorder component lists
`set`	Set SimBiology object properties
`setactiveconfigset (model)`	Set active configuration set for model object
`verify (model, variant)`	Validate and verify SimBiology model

Examples

collapse all

Construct a Simple Model

Open Live Script

This example shows you how to construct a simple model with two species (A and B) and a reaction. The reaction is A -> B, which follows mass action kinetics with the forward rate parameter k. Hence the rate of change is $d A / d t = - k * A$ .

Create a SimBiology model named simpleModel.

m1 = sbiomodel('simpleModel');

Add a reaction that involves two species A and B, where A is converted to B.

r1 = addreaction(m1,'A -> B');

SimBiology automatically add species A and B to the model.

m1.species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         unnamed         A        0               
   2         unnamed         B        0

Set the initial amount of the first species (A) to 10.

m1.species(1).InitialAmount = 10;

Define the kinetic law of the reaction to follow mass action kinetics. You can achieve this by adding a kinetic law object to the reaction r1.

kineticLaw = addkineticlaw(r1,'MassAction');

Add a rate constant parameter to the mass action kinetic law. You must set the ParameterVariableNames property of the kinetic law object to the name of the parameter 'k' so that the reaction rate can be determined.

p1 = addparameter(kineticLaw,'k',0.5);
kineticLaw.ParameterVariableNames = 'k';

Simulate the model.

sd = sbiosimulate(m1);

Plot the simulation results.

sbioplot(sd);

Figure contains an axes object. The axes object with title States versus Time, xlabel Time, ylabel States contains 2 objects of type line. These objects represent A, B.

Model Gene Regulation Pathway

Open Live Script

Create a model.

Mobj = sbiomodel('cell')

Mobj = 
   SimBiology Model - cell 

   Model Components:
     Compartments:      0
     Events:            0
     Parameters:        0
     Reactions:         0
     Rules:             0
     Species:           0
     Observables:       0

Add a compartment.

compObj = addcompartment(Mobj,'comp');
compObj.CapacityUnits = 'liter';

Add a reaction for transcription.

Robj1 = addreaction(Mobj,'DNA -> DNA + mRNA');

Display species.

Mobj.Species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         comp            DNA      0               
   2         comp            mRNA     0

Set initial amount for species DNA.

Mobj.Species(1).InitialAmount       = 50;
Mobj.Species(1).InitialAmountUnits  = 'molecule';
Mobj.Species(2).InitialAmountUnits  = 'molecule';

Add kinetic law.

Kobj1 = addkineticlaw(Robj1,'MassAction');

Display parameterVariables.

Kobj1.ParameterVariables

ans = 1x1 cell array
    {'Forward Rate Parameter'}

Display speciesVariables.

Kobj1.SpeciesVariables

ans = 1x1 cell array
    {'MassAction Species'}

Create a parameter k1.

Pobj1               = addparameter(Kobj1,'k1');
Pobj1.Value         = 0.2;
Pobj1.ValueUnits    = '1/second';
Kobj1.ParameterVariableNames = 'k1';

Display speciesVariableNames.

Kobj1.SpeciesVariableNames

ans = 1x1 cell array
    {'DNA'}

Display reaction rate of Robj1.

Robj1.ReactionRate

ans = 
'k1*DNA'

Add a reaction for translation and set its kinetic law.

Robj2 = addreaction(Mobj,'mRNA -> mRNA + protein');
Mobj.Species(3).InitialAmountUnits = 'molecule';
Kobj2 = addkineticlaw(Robj2,'MassAction');

Define the reaction rate constant k2 for the reaction.

Pobj2               = addparameter(Kobj2,'k2');
Pobj2.Value         = 20;
Pobj2.ValueUnits    = '1/second';
Kobj2.ParameterVariableNames = 'k2';

Display the reaction rate of Robj2.

Robj2.ReactionRate

ans = 
'k2*mRNA'

Add reactions for gene regulation.

Robj3 = addreaction(Mobj,'DNA + protein <-> DNAProteinComplex');
Mobj.Species(4).InitialAmountUnits = 'molecule';
Kobj3 = addkineticlaw(Robj3,'MassAction');
Pobj3 = addparameter(Kobj3,'k3','Value',0.2,'ValueUnits','1/(molecule*second)');
Pobj3r = addparameter(Kobj3,'k3r','Value',1.0,'ValueUnits','1/second');
Kobj3.ParameterVariableNames = {'k3','k3r'};

Display the reaction rate of Robj3.

Robj3.ReactionRate

ans = 
'k3*DNA*protein - k3r*DNAProteinComplex'

Add reactions for mRNA degradation to nucleotides.

Robj4 = addreaction(Mobj,'mRNA -> null');
Kobj4 = addkineticlaw(Robj4, 'MassAction');
Pobj4 = addparameter(Kobj4,'k4','Value',1.5,'ValueUnits','1/second');
Kobj4.ParameterVariableNames = 'k4';

Display the reaction rate of Robj4.

Robj4.ReactionRate

ans = 
'k4*mRNA'

Add reaction for protein degradation to amino acids.

Robj5 = addreaction(Mobj,'protein -> null');
Kobj5 = addkineticlaw(Robj5,'MassAction');
Pobj5 = addparameter(Kobj5,'k5','Value',1.0,'ValueUnits','1/second');
Kobj5.ParameterVariableNames = 'k5';

Display the reaction rate of Robj5.

Robj5.ReactionRate

ans = 
'k5*protein'

Turn on unit conversion by using the configset object.

configset = getconfigset(Mobj);
configset.CompileOptions.UnitConversion = true;

Simulate the model.

[t, simdata, names] = sbiosimulate(Mobj);

Plot the results.

plot(t,simdata)
legend(names,'Location','NorthEastOutside')
title('Gene Regulation');
xlabel('Time');
ylabel('Species Amount');

Figure contains an axes object. The axes object with title Gene Regulation, xlabel Time, ylabel Species Amount contains 4 objects of type line. These objects represent DNA, mRNA, protein, DNAProteinComplex.

Version History

Introduced in R2006b

expand all

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.

SimBiology.Model

Description

Creation

Properties

Compartments — Compartments in model empty array (default) | array of SimBiology.Compartment objects

Events — Events in model empty array (default) | array of SimBiology.Event objects

Name — Name of model character vector | string scalar

Notes — HTML text describing SimBiology object empty character array (default) | character vector | string scalar

Observables — Expressions for post-simulation calculations empty array (default) | array of SimBiology.Observable objects

Parent — Parent object SimBiology.Root object

Parameters — Parameters in model empty array (default) | array of SimBiology.Parameter objects

Reactions — Reactions in model empty array (default) | array of SimBiology.Reaction objects

Rules — Rules in model empty array (default) | array of SimBiology.Rule objects

Species — Species in SimBiology.Model empty SimBiology.Species array (default) | array of SimBiology.Species objects

Tag — Object label empty character array (default) | character vector | string

Type — Object type 'sbiomodel' (default)

UserData — Data to associate with model object scalar | vector | string | ...

Object Functions

Examples

Construct a Simple Model

Model Gene Regulation Pathway

Version History

R2024a: Having duplicate model component names is no longer allowed

R2022b: Having duplicate model component names issues a warning

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

See Also

`Compartments` — Compartments in model
empty array (default) | array of `SimBiology.Compartment` objects

`Events` — Events in model
empty array (default) | array of `SimBiology.Event` objects

`Name` — Name of model
character vector | string scalar

`Notes` — HTML text describing SimBiology object
empty character array (default) | character vector | string scalar

`Observables` — Expressions for post-simulation calculations
empty array (default) | array of `SimBiology.Observable` objects

`Parent` — Parent object
`SimBiology.Root` object

`Parameters` — Parameters in model
empty array (default) | array of `SimBiology.Parameter` objects

`Reactions` — Reactions in model
empty array (default) | array of `SimBiology.Reaction` objects

`Rules` — Rules in model
empty array (default) | array of `SimBiology.Rule` objects

`Species` — Species in `SimBiology.Model`
empty `SimBiology.Species` array (default) | array of `SimBiology.Species` objects

`Tag` — Object label
empty character array (default) | character vector | string

`Type` — Object type
`'sbiomodel'` (default)

`UserData` — Data to associate with model object
scalar | vector | string | ...