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

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

Construct a Simple Model

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 $dA/dt=-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);

Model Gene Regulation Pathway

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');

Version History

Introduced in R2006b

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.