addspecies

Create species object and add to model or compartment

Syntax

speciesObj = addspecies(modelCompartmentObj,speciesName)

speciesObj = addspecies(modelCompartmentObj,speciesName,initialValue)

speciesObj = addspecies(___,Name=Value)

Description

speciesObj = addspecies(modelCompartmentObj,speciesName) creates and returns a Species object speciesObj. The function also assigns

• speciesName to the Name property of speciesObj.

• modelCompartmentObj to the Parent property of speciesObj.

• speciesObj to the Species property of the model object or compartment object modelCompartmentObj.

• A value of 0 to the Value property of speciesObj.

speciesObj = addspecies(modelCompartmentObj,speciesName,initialValue) also assigns the Value property of speciesObj to initialValue.

speciesObj = addspecies(___,Name=Value) also sets the properties of speciesObj using one or more name-value arguments. Name is the property name and Value is the corresponding value.

Examples

Add Species to SimBiology Model

Create a model and add a compartment.

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.

speciesObj1.Value = 100

speciesObj1 = 
   SimBiology Species Array

   Index:    Compartment:    Name:                  Value:    Units:
   1         comp1           glucose_6_phosphate    100             

modelObj now contains an array of species.

modelObj.Species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:                                Value:    Units:
   1         comp1           glucose_6_phosphate                  100             
   2         comp1           glucose_6_phosphate_dehydrogenase    0               

Retrieve information about the first species in the array.

modelObj.Species(1)

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:                  Value:    Units:
   1         comp1           glucose_6_phosphate    100             

Input Arguments

modelCompartmentObj — SimBiology model or compartment

SimBiology.Model | SimBiology.Compartment

SimBiology model or compartment, specified as a Model or Compartment object.

If the input is a model which does not contain any compartments, the function creates a compartment called "unnamed" and adds the species to the compartment.

If there is more than one compartment 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 setspecies (kineticlaw) to configure SpeciesVariableNames. Species names are automatically updated for reactions that use MassAction kinetic law.

speciesName — Name of species

character vector | string scalar

Name of the species object, specified as a character vector or string scalar.

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.

Species objects are identified by name within other expressions and properties, such as Event, ReactionRate, and Rule. You can use sbioselect to find an object with a specific Name property value.

For tips on naming, see Guidelines for Naming Model Components.

Data Types: char | string

initialValue — Value of species

0 (default) | positive scalar

Value of the species, specified as a positive scalar.

Data Types: double

Version History

Introduced in R2006a

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.