mass.core.mass_reaction

MassReaction is a class for holding information regarding reactions.

The MassReaction class inherits and extends the Reaction class in cobra. It contains additional information required for simulations and other mass functions and workflows.

Some key differences between the cobra.Reaction and the mass.MassReaction are listed below:

• When instantiating a MassReaction from a cobra.Reaction, any associated cobra.Metabolite will also be converted into a MassMetabolite.

• Unlike the cobra.Reaction which initializes the lower_bound at a default value of 0.0, the MassReaction initializes the lower_bound as None to utilize the default value set in the MassConfiguration.

• The MassReaction contains both the steady_state_flux and the inherited cobra.Reaction.flux attributes. Note that these attributes DO NOT refer to the same flux value unless specifically set as such. The flux refers to the flux value in the most recent optimization solution, while the steady_state_flux refers to the net steady state flux through the reaction.

• The MassReaction contains both the reversible and reversibility attributes.

  Note that these attributes are NOT the same. While the reversible refers the the kinetic reversibility of the reaction and thus determines how the rate is set, while the inhertied cobra.Reaction.reversibility refers to the computed reversibility based on the current lower and upper bounds.

• The arrow in the string representation of the reaction is dependent on the MassReaction.reversible rather than the inhertied cobra.Reaction.reversibility attribute.

Module Contents

Classes

MassReaction

Class for holding kinetic information regarding a biochemical reaction.

class mass.core.mass_reaction.MassReaction(id_or_reaction=None, name='', subsystem='', reversible=True, steady_state_flux=None, **kwargs)

Bases: cobra.core.reaction.Reaction

Class for holding kinetic information regarding a biochemical reaction.

Accepted kwargs are passed onto the initialization method for the base class Reaction.

Parameters

• id_or_reaction (str, Reaction, MassReaction) – A string identifier to associate with the reaction, or an existing reaction. If an existing reaction object is provided, a new MassReaction object is instantiated with the same properties as the original reaction.

• name (str) – A human readable name for the reaction.

• subsystem (str) – The subsystem where the reaction is meant to occur.

• reversible (bool) – The kinetic reversibility of the reaction. Irreversible reactions have an equilibrium constant and a reverse rate constant as set in the irreversible_Keq and irreversible_kr attributes of the MassConfiguration. Default is True.

• **kwargs –

  lower_boundfloat or None

  The lower flux bound for optimization. If None then the default bound from the MassConfiguration is used.

  Default is None.

  upper_boundfloat or None

  The upper flux bound for optimization. If None then the default bound from the MassConfiguration is used.

  Default is None.

property reversible

Get or set the kinetic reversibility of the reaction.

When using a HistoryManager context, this attribute can be set temporarily, reversed when the exiting the context.

Parameters

reversible (bool) – The kinetic reversibility of the reaction.

Warning

Changing the reversible attribute will reset the equilibrium_constant and the reverse_rate_constant to the initialization defaults.

property steady_state_flux

Get or set the steady state flux of the reaction.

When using a HistoryManager context, this attribute can be set temporarily, reversed when the exiting the context.

Parameters

flux_value (bool) – The steady state flux value of the reaction.

property forward_rate_constant

Get or set the forward rate constant (kf) of the reaction.

When using a HistoryManager context, this attribute can be set temporarily, reversed when the exiting the context.

Notes

Forward rate constants cannot be negative.

Parameters

value (float) – A non-negative number for the forward rate constant (kf) of the reaction.

Raises

ValueError – Occurs when trying to set a negative value.

property reverse_rate_constant

Get or set the reverse rate constant (kr) of the reaction.

When using a HistoryManager context, this attribute can be set temporarily, reversed when the exiting the context.

Notes

• Reverse rate constants cannot be negative.

• If reaction is not reversible, will warn the user instead of setting the parameter value.

Parameters

value (float) – A non-negative number for the reverse rate constant (kr) of the reaction.

Raises

ValueError – Occurs when trying to set a negative value.

property equilibrium_constant

Get or set the equilibrium constant (Keq) of the reaction.

When using a HistoryManager context, this attribute can be set temporarily, reversed when the exiting the context.

Notes

• Equilibrium constants cannot be negative.

• If reaction is not reversible, will warn the user instead of setting the parameter value.

Parameters

value (float) – A non-negative number for the equilibrium constant (Keq) of the reaction.

Raises

ValueError – Occurs when trying to set a negative value.

property parameters

Return a dict of rate and equilibrium constants.

Notes

The reverse_rate_constant is only included for reversible reactions. Additionally, only rate and equilibrium constants are accessed here. Steady state fluxes can be accessed through the steady_state_flux attribute, and custom parameters can only be accessed through the model.

property metabolites

Return the metabolites of a reaction as a read only copy.

property reactants

Return a list of reactants for the reaction.

property products

Return a list of products for the reaction.

property stoichiometry

Return a list containing the stoichiometry for the reaction.

property rate

Return the current rate as a sympy expression.

If reaction has a custom rate in its associated MassModel, the custom rate will be returned instead.

property model

Return the MassModel associated with the reaction.

property reaction

Get or set the reaction as a human readable string.

Parameters

reaction_str (str) – String representation of the reaction.

Warning

Care must be taken when setting a reaction using this method. See documentation for build_reaction_from_string() for more information.

See also

build_reaction_string

Base function for getter method.

property compartments

Return the set of compartments where the metabolites are located.

property boundary

Determine whether or not the reaction is a boundary reaction.

Will return True if the reaction has no products or no reactants and only one metabolite.

Notes

These are reactions with a sink or a source term (e.g. ‘A –> ‘)

property boundary_metabolite

Return an ‘boundary’ metabolite for bounary reactions.

Notes

The ‘boundary_metabolite’ represents the metabolite that corresponds to the empty part of a boundary reaction through a string. It’s primary use is for setting of the boundary_conditions without creating a MassMetabolite object. Therefore it is not counted as a metabolite but instead as a parameter.

Returns

boundary_metabolite – String representation of the boundary metabolite of the reaction, or None if the reaction is not considered a boundary reaction.

Return type

str

See also

boundary

Method must return True to get the boundary_metabolite.

property genes

Return a frozenset of the genes associated with the reaction.

property gene_reaction_rule

Get or set the gene reaction rule for the reaction.

Parameters

new_rule (str) – String representation of the new reaction rule.

Notes

New genes will be associated with the reaction and old genes will be dissociated from the reaction.

property gene_name_reaction_rule

Display gene_reaction_rule with names.

Warning

Do NOT use this string for computation. It is intended to give a representation of the rule using more familiar gene names instead of the often cryptic ids.

property functional

Check if all required enzymes for the reaction are functional.

Returns

Returns True if the gene-protein-reaction (GPR) rule is fulfilled for the reaction, or if the reaction does not have an assoicated MassModel. Otherwise returns False.

Return type

bool

property flux_symbol_str

Return the string representation for the reaction flux symbol.

property all_parameter_ids

Return list of strings representing non-custom parameters.

property kf_str

Return the string representation of the forward rate constant.

property Keq_str

Return the string representation of the equilibrium constant.

property kr_str

Return the string representation of the reverse rate constant.

property kf

Alias for the forward_rate_constant.

property kr

Alias for the reverse_rate_constant.

property Keq

Alias for the equilibrium_constant.

property S

Alias for the stoichiometry.

property v

Alias for the steady_state_flux.

reverse_stoichiometry(inplace=False, reverse_parameters=False, reverse_bounds=True, reverse_flux=True)

Reverse the stoichiometry of the reaction.

Reversing the stoichiometry will turn the products into the reactants and the reactants into the products.

Notes

To avoid errors when reversing the reaction equilibrium constant:

• If self.equilibrium_constant=0. then new_reaction.equilibrium_constant=float("inf")

• If self.equilibrium_constant=float("inf") then new_reaction.equilibrium_constant=0.

Parameters

• inplace (bool) – If True, modify the reaction directly. Otherwise a new reaction is created, modified, and returned.

• reverse_parameters (bool) –

  If True then also switch the reaction rate constants and inverse the equilibrium constants such that:

  new_reaction.forward_rate_constant = self.reverse_rate_constant
  new_reaction.reverse_rate_constant = self.forward_rate_constant
  new_reaction.equilibrium_constant = 1/self.equilibrium_constant
  

  Default is False.

• reverse_bounds (bool) –

  If True then also switch the lower and upper bounds with one another such that:

  new_reaction.bounds = (-self.upper_bound, -self.lower_bound)
  

  Default is True.

• reverse_flux (bool) –

  If True then also switch the direction of the flux such that:

  new_reaction.steady_state_flux = -self.steady_state_flux
  

  Default is True.

Returns

new_reaction – Returns the original MassReaction if inplace=True. Otherwise return a modified copy of the original reaction.

Return type

MassReaction

get_mass_action_rate(rate_type=1, update_reaction=False, destructive=False)

Get the mass action rate law for the reaction.

Parameters

• rate_type (int) –

  The type of rate law to return. Must be 1, 2, or 3.

  • Type 1 will utilize the forward_rate_constant and the equilibrium_constant.

  • Type 2 will utilize the forward_rate_constant and the reverse_rate_constant.

  • Type 3 will utilize the equilibrium_constant and the reverse_rate_constant.

  Default is 1.

• update_reaction (bool) – Whether to update the MassReaction.rate attribute in addition to returning the rate law. Default is False.

• destructive (bool) – If True and the reaction has a custom rate law in its associated model, then setting update_reaction=True will replace the rate law and remove the custom rate law and orphaned parameters from the model. Default is False.

Returns

rate_expression – The rate law as a sympy expression. If the reaction has no metabolites associated, None will be returned.

Return type

sympy.core.basic.Basic or None

Warning

Setting update_reaction=True will not remove any associated custom rate laws from the model unless destructive=True as well.

get_forward_mass_action_rate_expression(rate_type=None)

Get the forward mass action rate expression for the reaction.

Parameters

rate_type (int, None) –

The type of rate law to return. Must be 1, 2, or 3.

• Type 1 and 2 will utilize the forward_rate_constant.

• Type 3 will utilize the equilibrium_constant and the reverse_rate_constant.

If None, the current rate type will be used. Default is None.

Returns

fwd_rate – The forward rate as a sympy expression. If the reaction has no metabolites associated, None will be returned.

Return type

sympy.core.basic.Basic or None

get_reverse_mass_action_rate_expression(rate_type=1)

Get the reverse mass action rate expression for the reaction.

Parameters

rate_type (int, None) –

The type of rate law to return. Must be 1, 2, or 3.

• Type 1 will utilize the forward_rate_constant and the equilibrium_constant.

• Type 2 and 3 will utilize the reverse_rate_constant.

If None, the current rate type will be used. Default is None.

Returns

rev_rate – The reverse rate as a sympy expression. If the reaction has no metabolites associated, None will be returned.

Return type

sympy.core.basic.Basic or None

get_mass_action_ratio()

Get the mass action ratio as a sympy expression.

Returns

The mass action ratio as a sympy expression.

Return type

sympy.core.basic.Basic

get_disequilibrium_ratio()

Get the disequilibrium ratio as a sympy expression.

Returns

The disequilibrium ratio as a sympy expression.

Return type

sympy.core.basic.Basic

copy()

Copy a reaction.

The reaction parameters, referenced metabolites, and genes are also copied.

get_coefficient(metabolite_id)

Return the coefficient of a metabolite in the reaction.

Parameters

metabolite_id (str or MassMetabolite) – The MassMetabolite or the string identifier of the metabolite whose coefficient is desired.

get_coefficients(metabolite_ids)

Return coefficients for a list of metabolites in the reaction.

Parameters

metabolite_ids (iterable) – Iterable containing the MassMetabolites or their string identifiers.

add_metabolites(metabolites_to_add, combine=True, reversibly=True)

Add metabolites and their coefficients to the reaction.

If the final coefficient for a metabolite is 0 then it is removed from the reaction.

The change is reverted upon exit when using the MassModel as a context.

Notes

• A final coefficient of < 0 implies a reactant and a final coefficient of > 0 implies a product.

• Extends add_metabolites() of the cobra.Reaction by first ensuring that the metabolites to be added are MassMetabolites and not cobra.Metabolites. and error message raised reflects the mass object.

• If a cobra.Metabolite is provided. a warning is raised and a MassMetabolite will be instantiated using the cobra.Metabolite.

Parameters

• metabolites_to_add (dict) – A dict with MassMetabolites or metabolite identifiers as keys and stoichiometric coefficients as values. If keys are strings (id of a metabolite), the reaction must already be part of a MassModel and a metabolite with the given id must already exist in the MassModel.

• combine (bool) – Describes the behavior of existing metabolites. If True, the metabolite coefficients are combined together. If False the coefficients are replaced.

• reversibly (bool) – Whether to add the change to the context to make the change reversible (primarily intended for internal use).

See also

subtract_metabolites()

subtract_metabolites(metabolites, combine=True, reversibly=True)

Subtract metabolites and their coefficients from the reaction.

This function will ‘subtract’ metabolites from a reaction by adding the given metabolites with -1 * coeffcient. If the final coefficient for a metabolite is 0, the metabolite is removed from the reaction.

The change is reverted upon exit when using the MassModel as a context.

Notes

• A final coefficient of < 0 implies a reactant and a final coefficient of > 0 implies a product.

• Extends cobra.core.reaction.Reaction.subtract_metabolites() of the cobra.Reaction by first ensuring that the metabolites to be added are MassMetabolites and not cobra.Metabolites. and error message raised reflects the mass object.

• If a cobra.Metabolite is provided. a warning is raised and a MassMetabolite will be instantiated using the cobra.Metabolite.

Parameters

• metabolites (dict) – A dict with MassMetabolites or their identifiers as keys and stoichiometric coefficients as values. If keys are strings (id of a metabolite), the reaction must already be part of a MassModel and a metabolite with the given id must already exist in the MassModel.

• combine (bool) – Describes the behavior of existing metabolites. If True, the metabolite coefficients are combined together. If False the coefficients are replaced.

• reversibly (bool) – Whether to add the change to the context to make the change reversible (primarily intended for internal use).

See also

add_metabolites()

build_reaction_string(use_metabolite_names=False)

Generate a human readable string to represent the reaction.

Notes

Overrides build_reaction_string() of the cobra.Reaction so that the reaction arrow depends on MassReaction.reversible rather than the inherited cobra.Reaction.reversibility attribute.

Parameters

use_metabolite_names (bool) – If True, use the metabolite names instead of their identifiers. Default is False.

Returns

reaction_string – A string representation of the reaction.

Return type

str

check_mass_balance()

Compute the mass and charge balances for the reaction.

Returns

Returns a dict of {element: amount} for unbalanced elements, with the “charge” treated as an element in the dict. For a balanced reaction, an empty dict is returned.

Return type

dict

build_reaction_from_string(reaction_str, verbose=True, fwd_arrow=None, rev_arrow=None, reversible_arrow=None, term_split='+')

Build reaction from reaction equation reaction_str using parser.

Takes a string representation of the reaction and uses the specifications supplied in the optional arguments to infer a set of metabolites, metabolite compartments, and stoichiometries for the reaction. It also infers the refversibility of the reaction from the reaction arrow.

For example:

• 'A + B <=> C' for reversible reactions, A & B are reactants.

• 'A + B --> C' for irreversible reactions, A & B are reactants.

• 'A + B <-- C' for irreversible reactions, A & B are products.

The change is reverted upon exit when using the MassModel as a context.

Notes

Extends build_reaction_from_string() of the cobra.Reaction in order to change how the irreversible backwards arrow is interpreted, affecting the assignment of reactants and products rather than how the bounds are set.

Parameters

• reaction_str (str) – A string containing the reaction formula (equation).

• verbose (bool) – Setting the verbosity of the function. Default is True.

• fwd_arrow (re.compile, None) – For forward irreversible reaction arrows. If None, the arrow is expected to be '-->' or '==>'.

• rev_arrow (re.compile, None) – For backward irreversible reaction arrows. If None, the arrow is expected to be '<--' or '<=='.

• reversible_arrow (re.compile, None) – For reversible reaction arrows. If None, the arrow is expected to be '<=>' or '<->'.

• term_split (str) – Dividing individual metabolite entries. Default is "+".

knock_out()

Knockout reaction by setting its bounds to zero.

_cobra_to_mass_repair()

Convert associated cobra.Metabolites to MassMetabolites for self.

Warning

This method is intended for internal use only.

_associate_gene(cobra_gene)

Associates a Gene with the reaction.

Parameters

cobra_gene (Gene) – Gene to be assoicated with the reaction.

Warning

This method is intended for internal use only.

_dissociate_gene(cobra_gene)

Dissociates a Gene with the reaction.

Parameters

cobra_gene (Gene) – Gene to be disassociated with the reaction.

Warning

This method is intended for internal use only.

_make_boundary_metabolites()

Make the boundary metabolite.

Warning

This method is intended for internal use only.

_repr_html_()

HTML representation of the overview for the MassReaction.

Warning

This method is intended for internal use only.

__copy__()

Create a copy of the MassReaction.

Warning

This method is intended for internal use only.

__deepcopy__(memo)

Create a deepcopy of the MassReaction.

Warning

This method is intended for internal use only.

__str__()

Create an id string with the stoichiometry.

Warning

This method is intended for internal use only.

__dir__()

Override default dir() implementation to list only public items.

Warning

This method is intended for internal use only.