Main Content

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

InitialAmountValueInitial amount value for the species object. Enter double. Positive real number, default is 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 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

copyobjCopy SimBiology object and its children
deleteDelete SimBiology object
displayDisplay summary of SimBiology object
findUsagesFind out how a species, parameter, or compartment is used in a model
getGet SimBiology object properties
moveMove SimBiology species or parameter object to new parent
renameRename SimBiology model component and update expressions
setSet SimBiology object properties

Property Summary

Properties for species objects

ActiveIndicate object in use during simulation
BoundaryConditionIndicate species boundary condition
Constant Specify variable or constant species amount, parameter value, or compartment capacity
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
Units Units for species amount, parameter value, compartment capacity, observable expression
UserDataSpecify data to associate with object
ValueValue 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.

  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: []

Version History

Introduced in R2006a

expand all