Documentation Center

  • Trial Software
  • Product Updates

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

compObjCompartment object.
modelObjModel object containing zero or one compartment.
NameValueName for a species object. Enter a character string unique among species within modelObj or compObj. Species objects are identified by name within Event, ReactionRate, and Rule property strings.

For information on naming species, see Name.

You can use the function sbioselect to find an object with a specific Name property value.

InitialAmountValueInitial amount value for the species object. Enter double. Positive real number, default = 0.
PropertyNameEnter the name of a valid property. Valid property names are listed in Property Summary.
PropertyValueEnter 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 string 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 (any object)Copy SimBiology object and its children
delete (any object)Delete SimBiology object
display (any object)Display summary of SimBiology object
get (any object)Get object properties
rename (compartment, parameter, species, reaction)Rename object and update expressions
set (any object)Set object properties

Property Summary

Properties for species objects

BoundaryConditionIndicate species boundary condition
ConstantAmount Specify variable or constant species amount
InitialAmountSpecies initial amount
InitialAmountUnitsSpecies initial amount units
NameSpecify name of object
NotesHTML text describing SimBiology object
ParentIndicate parent object
TagSpecify label for SimBiology object
TypeDisplay SimBiology object type
UserDataSpecify data to associate with object

Examples

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

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

    modelObj = sbiomodel ('my_model');
    compObj = addcompartment(modelObj, 'comp1');
  2. 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');
  3. Set the initial amount of glucose_6_phosphate to 100 and verify.

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

    MATLAB returns:

    ans =
    
       100
  4. 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                 
    
  5. 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: []
Was this topic helpful?