SimBiology.Species

Object containing species information

Description

The SimBiology.Species object represents a species, which is a chemical or entity that participates in reactions, for example, DNA, ATP, Pi, creatine, G-Protein, or Mitogen-Activated Protein Kinase (MAPK). Species amounts can vary or remain constant during a simulation. The name of each species must be unique within the same compartment and the species object cannot have the same name as any observable object in the model.

To add species that participate in reactions, add the reaction to the model. The process of adding the reaction to the model creates a compartment object (unnamed) and the necessary species objects.

Alternatively, create and add a species object to a compartment, using the addspecies function.

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 species, reactions, and other model components to your model and edit them. For an example, see Incorporate SGLT2 Inhibition into Physiologically Based Glucose-Insulin Model Using SimBiology Model Builder.

Creation

Use addspecies to create and add a species to a compartment.

Properties

InitialAmount — Species initial amount

0 (default) | positive scalar

Species initial amount, specified as a positive scalar. InitialAmount is the quantity of the species before the simulation starts.

The InitialAmount property and the Value property are identical.

Data Types: double

InitialAmountUnits — Species initial amount units

empty character array (default) | character vector | string scalar

Species initial amount units, specified as a character vector or string scalar. This property is identical to Units.

The property indicates the unit definition for the InitialAmount property of a species object.

The InitialAmountUnits property is identical to the Units property. For more details, see Units.

Example: "picomole/liter"

Data Types: char | string

ConstantAmount — Flag to set species value as constant

false or 0 (default) | true or 1

Flag to set the species value as a constant, specified as a numeric or logical 1 (true) or 0 (false). ConstantAmount is identical to Constant.

For more details, see the Constant property.

Data Types: double | logical

Constant — Flag to set species value as constant

false or 0 (default) | true or 1

Flag to set the species value as a constant, specified as a numeric or logical 1 (true) or 0 (false). ConstantAmount is identical to Constant.

The Constant property indicates whether the quantity of the species object can vary during the simulation. Constant can be either true or false. If Constant is true, the quantity of the species cannot vary during the simulation. By default, Constant is false and the quantity of the species can vary during the simulation. If Constant is false, the quantity of the species can be determined by reactions and rules.

Note

When you want the species to participate in a reaction, but do not want any reactions to modify its quantity, set its BoundaryCondition to true, and ConstantAmount to false.

The following is an example of modeling species as constant amounts.

Consider the role of nucleotides (GTP, ATP, cAMP) and cofactors (Ca⁺⁺, NAD⁺, coenzyme A). Consider the role of GTP in the activation of Ras by receptor tyrosine kinases: Ras-GDP + GTP -> Ras-GTP + GDP

Model GTP and GDP with constant amount set to true. In addition, you can set the BoundaryCondition of these species to true, thus making them boundary species.

Data Types: double | logical

Value — Species value

0 (default) | nonnegative scalar

Special value, specified as a nonnegative scalar.

The InitialAmount property and the Value property are identical.

Data Types: double

Units — Units for species value

empty character array (default) | character vector | string scalar

Units for the species value, specified as a character vector or string scalar.

Units can be one of the built-in units or you can create your own units. To get a list of the built-in units, use sbioshowunits. To create a custom unit, use sbiounit. If Units changes from one unit definition to another, the Value property does not automatically convert to the new units. sbioconvertunits does this conversion.

Note

SimBiology^® uses units including empty units in association with DimensionalAnalysis and UnitConversion features.

• When DimensionalAnalysis and UnitConversion are both false, units are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

• When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

• When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no units can be empty. If you have a dimensionless parameter, you must still set its unit to dimensionless.

See DefaultSpeciesDimension for more information on specifying dimensions for species quantities. Some examples of valid dimensions are amount, amount/length, amount/area, or amount/volume. InitialAmountUnits or Units must have corresponding dimensions to CapacityUnits. For example, if the CapacityUnits are meter², then species must be amount/meter² or amount.

Example: "milligram"

Data Types: char | string

BoundaryCondition — Flag to set species boundary condition

false or 0 (default) | true or 1

Flag to set the species boundary condition, specified as a numeric or logical 1 (true) or 0 (false). The property indicates whether reactions affect a species quantity.

When the BoundaryCondition property of a species is false, the reactions can modify the species quantity. If a species is modified by reactions, then rules (repeated assignment rule, rate rule, or algebraic rule) cannot modify its value. SimBiology considers a reaction to modify a species when the net stoichiometry for the species is non-zero. For example, the reaction X -> 2*X modifies X, but the reaction X + E -> Y + E does not modify E.

When BoundaryCondition is true, then the value of the species is not changed by reactions during model simulation, even if the net stoichiometry is non-zero. Set the BoundaryCondition of a species to true if you want the species to participate in the reaction but you want to determine the value of that species using a rule instead. For example, set the BoundaryCondition of species X to true to specify its value using a repeated assignment rule but also to use species X in a reaction with MassAction kinetics, for example, X + Y -> Z.

For details on how these two properties affect a species quantity during simulation, see How Species Amounts Change During Simulations.

Consider the following two use cases of boundary conditions:

• Modeling receptor-ligand interactions that affect the rate of change of the receptor but not the ligand. For example, in response to hormone, steroid receptors such as the glucocorticoid receptor (GR) translocate from the cytoplasm (cyt) to the nucleus (nuc). The hsp90/ hsp70 chaperone complex directs this nuclear translocation [1]. The natural ligand for GR is cortisol; the synthetic hormone dexamethasone (dex) is used in place of cortisol in experimental systems. In this system dexamethasone participates in the reaction but the quantity of dexamethasone in the cell is regulated using a rule. To simply model translocation of GR you could use the following reactions:

  Formation of the chaperone-receptor complex,

  Hsp90_complex + GR_cyt -> Hsp90_complex:GR_cyt
  

  In response to the synthetic hormone dexamethasone (dex), GR moves from the cytoplasm to the nucleus.

  Hsp90_complex:GR_cyt + dex -> Hsp90_complex + GR_nuc + dex
  

  For dex,

   BoundaryCondition = true; ConstantAmount = false

  In this example dex is modeled as a boundary condition with a rule to regulate the rate of change of dex in the system. Here, the quantity of dex is not determined by the rate of the second reaction but by a rate rule such as

  ddex/dt = 0.001 

  which is specified in the SimBiology software as

  dex = 0.001

• Modeling the role of nucleotides (for example, GTP, ATP, cAMP) and cofactors (for example, Ca⁺⁺, NAD⁺, coenzyme A). Consider the role of GTP in the activation of Ras by receptor tyrosine kinases.

  Ras-GDP + GTP  -> Ras-GTP + GDP

  For GTP, BoundaryCondition = true; ConstantAmount = true

  Model GTP and GDP with boundary conditions, thus making them boundary species. In addition, you can set the Constant property of these species to true to indicate that their quantity does not vary during a simulation.

Data Types: double | logical

Name — SimBiology.Species object name

character vector | string

SimBiology.Species 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

Parent — Parent object

Read-only: SimBiology.Compartment object

This property is read-only.

Parent object, specified as a SimBiology.Compartment object.

Notes — Additional information

empty character array (default) | character vector | string

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

Data Types: char | string

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

Read-only: 'species' (default)

This property is read-only.

Object type, specified as 'species'. 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

copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
findUsages	Find out how a species, parameter, or compartment is used in a model
get	Get SimBiology object properties
move	Move SimBiology species or parameter object to new parent
rename	Rename SimBiology model component and update expressions
set	Set SimBiology object properties

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

Simulate SimBiology Model with Boundary Condition for Species

This example illustrates how to use the BoundaryCondition property of a species so that the species amount is not modified by the reaction it participates in, but by a user-defined dose object.

Load a sample project.

sbioloadproject radiodecay.sbproj

A SimBiology model named m1 is loaded to the MATLAB Workspace. The model is a simple radioactive decay model in which two species (x and z) are modified by the following reaction.k

m1.Reactions

ans = 
   SimBiology Reaction Array

   Index:    Reaction:
   1         x -> z   

Simulate the model and view results before adding any boundary conditions.

[t,x,names] = sbiosimulate(m1);
plot(t,x);
legend(names)
xlabel('Time');
ylabel('Amount');

Add a RepeatDose object to the model and specify the species to be dosed, dose amount, dose schedule, and units.

d1 = adddose(m1,'d1','repeat');
set(d1,'TargetName','z','Amount',100.0,'Interval',1.0,'RepeatCount',8);
set(d1,'TimeUnits','second','AmountUnits','molecule');

Set the BoundaryCondition of species z to be true so that the species will be modified by the dose object d1, but not by the reaction.

set(m1.species(2),'BoundaryCondition',true);

Simulate the model by applying the dose object.

[t2,x2,names] = sbiosimulate(m1,d1);

Plot the results. Notice that the amount of species z is now modified by the repeated dose object, but not by the reaction.

[t2,x2,names] = sbiosimulate(m1,d1);
plot(t2,x2);
legend(names);
xlabel('Time');
ylabel('Amount');

References

[1] Pratt, William B, Mario D Galigniana, Yoshihiro Morishima, and Patrick J M Murphy. “Role of Molecular Chaperones in Steroid Receptor Action.” Edited by Iain J. McEwan. Essays in Biochemistry 40 (June 1, 2004): 41–58.

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.