m = pwAddR(m, ID, reactants, products, modifiers, type, ...
            options, rateSignature, parameters, description, ...
            name, fast, compartments, parameterTrunks, designerPropsR,...
            stoichiometry, reversible);
 m = pwAddR(m, interactive)

 Adds a reaction to a model.

 NEW SYNTAX SINCE PW 3.0: The reaction ID is now the second argument as in all
 similar functions like pwAddX and pwAddY.

  pwAddR((m, reactants, products, modifiers, type, options, rateSignature, parameters, description, ID, name, ...)
  pwAddR((m, ID, reactants, products, modifiers, type, options, rateSignature, parameters, description, name, ...)

 For each reaction the reactants, products, modifiers such as
 enzymes, kinetic information and parameters are specified.
 Additionally, an optionally reaction description, ID, name and
 compartment information may be entered.


Arguments for pwAddR

  1 ID               ID          If a reaction exists with the same ID,
                                 the old reaction will be overwritten.
                                 A warning will be shown if
                                 config.model.warnWhenOverridingR is true.
  2 reactants        ID array    IDs of the used reactants, e.g. {'Erk', 'Mek'}
                                 Please follow the PottersWheel naming convention:
                                 Basic species start with an upper case letter, e.g. Erk
                                 Modifications are lower case prefixes, e.g. pErk
                                 Bindings are denoted by an underscore, e.g. pMek_Erk
  3 products         ID array    IDs of the products
  4 modifiers        ID array    IDs of the modifiers
  5 type             string      Type of the rate kinetics (see below):
                                 'A', 'C', 'D', 'MM', 'MM2', 'Hill'
                                 A    automatic (default, see below)
                                 C    Custom
                                 D    Delay
                                 MM   Michaelis-Menten with Enzyme
                                 MM2  Michaelis-Menten 2 with Vmax
                                 Hill Sigmoidal kinetics
  6 options          integer
  7 rateSignature    string
  8 parameters       ID array
  9 description      string
 10 name             string
 11 fast             integer     1 yes, 0 no (default)
 12 compartments     ID array
 13 parameterTrunks  string array
 14 designerPropsR   cell array  Visualization properties (internal use):
                              {[x y z], [indR r g b w s1 s2 s3; ...],
                                        [indP r g b w s1 s2 s3; ...],
                                        [indM r g b w s1 s2 s3; ...]};
 15 stoichiometry    cell array Only required for fractional stoichiometry.
                                Example: {'Erk', 0.8, 'Mek', 3.4}
 16 reversible       boolean    True, if the reaction is reversible.
                                Please note that actually only the rate signature
                                determines the reversibility of the reaction.
                                But for compatibility with SBML, this property
                                can be set explicitely. If left empty, the
                                reversibility will be set to false, if the
                                rate signature does not contain any minus sign.

 Alternative function call for interactive specification:
 interactive         boolean   If true, the user is prompted to enter the properties
                               into a user interface.



 String arguments which may have more than one entry, e.g. the
 reactants, are entered as string cell arrays, e.g.
 {'Reactant1','Reactant2','Reactant3'}. This applies
 also to the products, modifiers, parameters and compartments.

 Reaction types are either determined automatically (A),
 are predefined (MM, Hill), correspond to a delay (D) or
 are customly specified by the user (C).

 A simple irreversible reaction A -> B with mass action
 kinetics and rate AtoB could be specified via

  m = pwAddR(m, [], {'A'}, {'B'}, {}, 'C', [], 'k1 * r1', {'AtoB'});

 Here, {} and [] are used for empty arguments.
 The rate signature 'k1 * r1' reflects that the concentration of A is
 decreased per time unit by the first parameter k1, which is AtoB, times
 the first reactant r1, which is A. A reversible reaction A <-> B
 could be entered as two irreversible reactions
 A -> B and B -> A or via

  m = pwAddR(m, [], {'A'}, {'B'}, {}, 'C', [], 'k1*r1 - k2*p1', {'AtoB','BtoA'});

 introducing p1 as the placeholder for the first product, which is
 B. The second parameter BtoA is used in the rate signature via k2.

 In general, ri, pi, mi, ki, and ci are placeholders for the
 i-th reactant, product, modifier, parameter, and compartment
 of the current reaction. This way, the reaction kinetic is always
 specified in a simple text book like format and does not change
 from reaction to reaction as long as the underlying kinetics are the same.
 For example a Michaelis-Menten reaction will have always the rate signature

  'k1 * r1 * m1 / (k2 + r1)',

 independent of the current reaction number. Only the used reactants, products, modifiers,
 and parameters will be different for two different Michaelis-Menten reactions.

 Note: Curly brackets for the ID lists are only required if
 no or more than one ID appears in the list. Single IDs
 can be specified directly, e.g. 'S' instead of {'S'}.


Reaction types


C (custom)

 The rate signature is specified by the modeler using placeholders, e.g.

  'k1 * r1'

 for a rate which is proportional to the value of the first reactant.


A (automatic)

 If the reaction type is set to 'A', the rate signature is automatically
 determined based on the specified reactants, products, modifiers and parameters
 using mass action kinetics. If two parameters are specified, the reaction
 is assumed to be reversible. In detail:

 No parameter given:
  rateSignature = ProductOfAllReactantsAndAllModifiers.
 One parameter:
  rateSignature = k1 * ProductOfAllReactantsAndAllModifiers.
 Two parameters:
  rateSignature = k1 * ProductOfAllReactantsAndAllModifiers - k2 * ProductOfAllProducts.

 The old reaction types MA (mass action) and E (enzymatic) are obsolete and deprecated.
  MA: rateSignature = k1 * ProductOfAllReactants.
  E:  rateSignature = k1 * ProductOfAllReactants * m1.


MM (Michaelis-Menten)

 E:     Enzyme
 S:     Subtrate
 k_f:   rate constant of forward reaction
 k_r:   rate constant of reverse reaction
 k_cat: rate constant of catalysis
 kM:    (k_r + k_cat) / k_f

 E + S <-k_r--k_f-> E_S -k_cat-> E + P

 v = k_cat * E * S / (Km + S)

  rateSignature = 'k1 * r1 * m1 / (k2 + r1)'


MM2 (Michaelis-Menten 2)

 v = Vmax * S / (Km + S)

  rateSignature = 'k1 * r1 / (k2 + r1)'



  rateSignature = 'k1 * m1 * r1^k3 / (k2^k3 + r1^k3)'

 The parameter k3 should be larger than 0.5 to avoid instabilities during integration.
 A too large value may also hamper integration depending on the
 overall system properties.


D (Delay)

 The reaction A -> B is exploded into n reactions

  A -> A1 -> A2 -> ... -> A_{n-1} -> B

 with the same rate constant k1. The length of this linear
 chain trick is given by the options field. Too large values
 will make the system very stiff. Recommended values are in
 the order of 5 to 15.


Rule-based modeling

 Some models comprise combinatorial complexity, where reactions take place
 in parallel without a certain order, e.g. a receptor with several binding
 sites which are independent from each other. In order to avoid the
 redundant and error-prone formulation of all single reactions, rule-based
 modeling can be applied. Please see pwTutorial_Rule_based_modeling and
 pwAddX for further details.


Naming convention

 PottersWheel supports arbitrary IDs for reactants, products, and
 modifiers (for example, enzymes), as long as only letters, numbers
 and the underscore are used and the first character is not a
 numerical value. However, in order to make use of several features
 such as sub-reaction-networks and combinatorial complexity, the
 following conventions are recommended:

 - Basic species start with a capital letter, e.g. Erk and Mek

 - Modifications are lower case prefixes, e.g. pErk and ppErk

 - Species of a complex are separated by an underscore, e.g. pR_pR and Grb1_Grb2



 m = pwAddR(m, [], {'S'}, {'P'}, {}, 'C', [], 'k1 * r1 / (k2 + r1)', {'Vmax', 'Km'});

 is equivalent to

 m = pwAddR(m, [], {'S'}, {'P'}, {}, 'MM2', [], [], {'Vmax', 'Km'});

See also