addreaction (model)

Create reaction object and add to model object

Syntax

reactionObj = addreaction(modelObj,'ReactionValue')
reactionObj = addreaction(modelObj, 'ReactantsValue', 'ProductsValue')
reactionObj = addreaction(modelObj, 'ReactantsValue', RStoichCoefficients, 'ProductsValue', PStoichCoefficients)
reactionObj = addreaction(...'PropertyName', PropertyValue...)


Arguments

modelObj	SimBiology® model object.
ReactionValue	Specify the reaction equation. Enter a character vector. A hyphen preceded by a space and followed by a right angle bracket (->) indicates reactants going forward to products. A hyphen with left and right angle brackets (<->) indicates a reversible reaction. Coefficients before reactant or product names must be followed by a space. Examples are 'A -> B', 'A + B -> C', '2 A + B -> 2 C', and 'A <-> B'. Enter reactions with spaces between the species. If there are multiple compartments, or to specify the compartment name, use compartmentName.speciesName to qualify the species name. Examples are 'cytoplasm.A -> cytoplasm.B', 'cytoplasm.A -> nucleus.A', and 'cytoplasm.A + cytoplasm.B -> nucleus.AB'.
ReactantsValue	Character vector defining the species name, a cell array of character vectors, a species object, or an array of species objects. If using names, qualify with compartment names if there are multiple compartments.
ProductsValue	Character vector defining the species name, a cell array of character vectors, a species object, or an array of species objects. If using names, qualify with compartment names if there are multiple compartments.
RStoichCoefficients	Stoichiometric coefficients for reactants, length of array equal to length of ReactantsValue.
PStoichCoefficients	Stoichiometric coefficients for products, length of array equal to length of ProductsValue.

Note

If you qualify any species name with a compartment name, then you must qualify every species with the corresponding compartment name.

Description

reactionObj = addreaction(modelObj,'ReactionValue') creates a reaction object, assigns a value (ReactionValue) to the property Reaction, assigns reactant species object(s) to the property Reactants, assigns the product species object(s) to the property Products, and assigns the model object to the property Parent. In the Model object (modelObj), this method assigns the reaction object to the property Reactions, and returns the reaction object (reactionObj).

reactionObj = addreaction(modelObj, 'a -> b')

When you define a reaction with a new species:

• If no compartment objects exist in the model, the method creates a compartment object (called 'unnamed') in the model and adds the newly created species to that compartment.

• If only one compartment object (compObj) exists in the model, the method creates a species object in that compartment.

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

You can manually add a species to a compartment object with the method addspecies.

You can add species to a reaction object using the methods addreactant or addproduct. You can remove species from a reaction object with the methods rmreactant or rmproduct. The property Reaction is modified by adding or removing species from the reaction equation.

You can copy a SimBiology reaction object to a model object with the function copyobj. You can remove the SimBiology reaction object from a SimBiology model object with the function delete.

You can view additional reaction object properties with the get command. For example, the reaction equation of reactionObj can be viewed with the command get(reactionObj, 'Reaction'). You can modify additional reaction object properties with the command set.

reactionObj = addreaction(modelObj, 'ReactantsValue', 'ProductsValue') creates a reaction object, assigns a value to the property Reaction using the reactant (ReactantsValue) and product (ProductsValue) names, assigns the species objects to the properties Reactants and Products, and assigns the model object to the property Parent. In the model object (modelObj), this method assigns the reaction object to the property Reactions, and returns the reaction object (reactionObj). The stoichiometric values are assumed to be 1.

reactionObj = addreaction(modelObj, 'ReactantsValue', RStoichCoefficients, 'ProductsValue', PStoichCoefficients) adds stoichiometric coefficients (RStoichCoefficients) for reactant species, and stoichiometric coefficients (PStoichCoefficients) for product species to the property Stoichiometry. The length of Reactants and RCoefficients must be equal, and the length of Products and PCoefficients must be equal.

reactionObj = addreaction(...'PropertyName', PropertyValue...) defines optional properties. The property name/property value pairs can be in any format supported by the function set.

Note

If you use the addreaction method to create a reaction rate expression that is not continuous and differentiable, see Using Events to Address Discontinuities in Rule and Reaction Rate Expressions before simulating your model.

Method Summary

Methods for reaction objects

addkineticlaw (reaction)	Create kinetic law object and add to reaction object
addproduct (reaction)	Add product species object to reaction object
addreactant (reaction)	Add species object as reactant to reaction object
copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
getadjacencymatrix (model)	Get adjacency matrix from model object
getstoichmatrix (model)	Get stoichiometry matrix from model object
rename	Rename object and update expressions
rmproduct (reaction)	Remove species object from reaction object products
rmreactant (reaction)	Remove species object from reaction object reactants
set	Set SimBiology object properties

Property Summary

Properties for reaction objects

Active	Indicate object in use during simulation
KineticLaw	Show kinetic law used for ReactionRate
Name	Specify name of object
Notes	HTML text describing SimBiology object
Parent	Indicate parent object
Products	Array of reaction products
Reactants	Array of reaction reactants
Reaction	Reaction object reaction
ReactionRate	Reaction rate equation in reaction object
Reversible	Specify whether reaction is reversible or irreversible
Stoichiometry	Species coefficients in reaction
Tag	Specify label for SimBiology object
Type	Display SimBiology object type
UserData	Specify data to associate with object

Examples

Create a model, add a reaction object, and assign the expression for the reaction rate equation.

1. Create a model object, and then add a reaction object.

   modelObj = sbiomodel('my_model');
   reactionObj = addreaction(modelObj, 'a -> c + d');

2. Create a kinetic law object for the reaction object, of the type 'Henri-Michaelis-Menten'.

   kineticlawObj = addkineticlaw(reactionObj, 'Henri-Michaelis-Menten');

   reactionObj KineticLaw property is configured to kineticlawObj.

3. The 'Henri-Michaelis-Menten' kinetic law has two parameter variables (Vm and Km) and one species variable (S) that should to be set. To set these variables, first create the parameter variables as parameter objects (parameterObj1, parameterObj2) with names Vm_d, and Km_d, and assign the objects Parent property value to the kineticlawObj.

   parameterObj1 = addparameter(kineticlawObj, 'Vm_d');
   parameterObj2 = addparameter(kineticlawObj, 'Km_d');

4. Set the variable names for the kinetic law object.

   set(kineticlawObj,'ParameterVariableNames', {'Vm_d' 'Km_d'});
   set(kineticlawObj,'SpeciesVariableNames', {'a'});

5. Verify that the reaction rate is expressed correctly in the reaction object ReactionRate property.

   get (reactionObj, 'ReactionRate')

   MATLAB returns:

   ans =
   
   Vm_d*a/(Km_d+a)

Version History

Introduced in R2006a

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.