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
andUnitConversion
are bothfalse
, 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
istrue
andUnitConversion
isfalse
, 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 totrue
(which requiresDimensionalAnalysis
to betrue
), 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 todimensionless
.
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
2, then species must be
amount/meter
2 or
amount
.
Example:
"milligram"
Data Types: char
| string
BoundaryCodition
— 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.ForHsp90_complex:GR_cyt + dex -> Hsp90_complex + GR_nuc + dex
dex
,In this exampleBoundaryCondition = true; ConstantAmount = false
dex
is modeled as a boundary condition with a rule to regulate the rate of change ofdex
in the system. Here, the quantity ofdex
is not determined by the rate of the second reaction but by a rate rule such aswhich is specified in the SimBiology software asddex/dt = 0.001
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 totrue
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
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
'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 .
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 R2006bR2024a: 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.
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)