addspecies (model, compartment)

Create species object and add to compartment object within model object

Syntax

speciesObj = addspecies(compObj, 'NameValue') speciesObj = addspecies(compObj, 'NameValue', InitialAmountValue) speciesObj = addspecies(modelObj, 'NameValue') speciesObj = addspecies(modelObj, 'NameValue', InitialAmountValue) speciesObj = addspecies(...'PropertyName', PropertyValue...)

Arguments

`compObj`	`Compartment object`.
`modelObj`	`Model object` containing zero or one compartment.
`NameValue`	Name for a species object. Enter a character vector unique among species within `modelObj` or `compObj`. Species objects are identified by name within the `Event`, `ReactionRate`, and `Rule` properties. For information on naming species, see `Name`. You can use the function `sbioselect` to find an object with a specific `Name` property value.
`InitialAmountValue`	Initial amount value for the species object. Enter `double`. Positive real number, default is `0`.
`PropertyName`	Enter the name of a valid property. Valid property names are listed in Property Summary.
`PropertyValue`	Enter the value for the property specified in `PropertyName`. Valid property values are listed on each property reference page.

Description

speciesObj = addspecies(compObj, 'NameValue') creates speciesObj, a species object, and adds it to compObj, a compartment object. In the species object, this method assigns NameValue to the Name property, assigns compObj to the Parent property, and assigns 0 to the InitialAmount property. In the compartment object, this method adds the species object to the Species property.

speciesObj = addspecies(compObj, 'NameValue', InitialAmountValue), in addition to the above, assigns InitialAmountValue to the InitialAmount property for the species object.

speciesObj = addspecies(modelObj, 'NameValue') creates speciesObj, a species object, and adds it to compObj, the compartment object in modelObj, a Model object. If modelObj does not contain any compartments, it creates compObj with a Name property of 'unnamed'. In the species object, this method assigns NameValue to the Name property, assigns compObj to the Parent property, and assigns 0 to the InitialAmount property. In the compartment object, this method adds the species object to the Species property.

speciesObj = addspecies(modelObj, 'NameValue', InitialAmountValue), in addition to the above, assigns InitialAmountValue to the InitialAmount property for the species object.

You can also add a species to a reaction using the methods addreactant and addproduct.

A species object must have a unique name at the level at which it is created. For example, a compartment object cannot contain two species objects named H2O. However, another compartment can have a species named H2O.

View properties for a species object with the get command, and modify properties for a species object with the set command. You can view a summary table of species objects in a compartment (compObj) with get(compObj, 'Species') or the properties of the first species with get(compObj.Species(1)).

speciesObj = addspecies(...'PropertyName', PropertyValue...) defines optional properties. The property name/property value pairs can be in any format supported by the function set (for example, name-value pairs, structures, and name-value cell array pairs). The property summary on this page shows the list of properties.

If there is more than one compartment object (compObj) in the model, you must qualify the species name with the compartment name. For example, cell.glucose denotes that you want to put the species named glucose into a compartment named cell. Additionally, if the compartment named cell does not exist, the process of adding the reaction creates the compartment and names it cell.

If you change the name of a species you must configure all applicable elements, such as events and rules that use the species, any user-specified ReactionRate, or the kinetic law object property SpeciesVariableNames. Use the method setspecies to configure SpeciesVariableNames.

To update species names in the SimBiology^® graphical user interface, access each appropriate pane through the Project Explorer. You can also use the Find feature to locate the names that you want to update. The Output pane opens with the results of Find. Double-click a result row to go to the location of the model component.

Species names are automatically updated for reactions that use MassAction kinetic law.

Method Summary

Methods for species objects

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 object and update expressions
set	Set SimBiology object properties

Property Summary

Properties for species objects

Active	Indicate object in use during simulation
BoundaryCondition	Indicate species boundary condition
Constant	Specify variable or constant species amount, parameter value, or compartment capacity
ConstantAmount	Specify variable or constant species amount
InitialAmount	Species initial amount
InitialAmountUnits	Species initial amount units
Name	Specify name of object
Notes	HTML text describing SimBiology object
Parent	Indicate parent object
Tag	Specify label for SimBiology object
Type	Display SimBiology object type
Units	Units for species amount, parameter value, compartment capacity, observable expression
UserData	Specify data to associate with object
Value	Value of species, compartment, or parameter object

Examples

Add two species to a model, where one is a reactant and the other is the enzyme catalyzing the reaction.

Create a model object named my_model and add a compartment object.

modelObj = sbiomodel ('my_model');
compObj = addcompartment(modelObj, 'comp1');

Add two species objects named glucose_6_phosphate and glucose_6_phosphate_dehydrogenase.

speciesObj1 = addspecies (compObj, 'glucose_6_phosphate');
speciesObj2 = addspecies (compObj, ...
                         'glucose_6_phosphate_dehydrogenase');

Set the initial amount of glucose_6_phosphate to 100 and verify.

set (speciesObj1, 'InitialAmount',100);
get (speciesObj1, 'InitialAmount')

MATLAB returns:

ans =

   100

Use get to note that modelObj contains the species object array.

get(compObj, 'Species')

MATLAB returns:

SimBiology Species Array

Index: Name:                             InitialAmount: InitialAmountUnits:
 1     glucose_6_phosphate                100               
 2     glucose_6_phosphate_dehydrogenase  0

Retrieve information about the first species in the array.

get(compObj.Species(1))
            Annotation: ''
     BoundaryCondition: 0
        ConstantAmount: 0
         InitialAmount: 100
    InitialAmountUnits: ''
                  Name: 'glucose_6_phosphate'
                 Notes: ''
                Parent: [1x1 SimBiology.Compartment]
                   Tag: ''
                  Type: 'species'
              UserData: []

Version History

Introduced in R2006a

expand all

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. In a future release, within a single model, these components will be 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.
The purpose of this naming restriction is to ensure that every model component can be unambiguously referenced by its unique name within a model. For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.
To disambiguate duplicate names from your model, use the updateDuplicateNames function at the command line. The function takes in a SimBiology model as an input and updates the component names as necessary. You can also specify optional outputs, such as a logical flag to check whether any update occurred, a list of model changes, and a copy of the original model before any updates were made.
The updateDuplicateNames function 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.

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.