cobra.flux_analysis.spectra_cc#

Provide an implementation of the SPECTRA consistency check.

Attributes#

Functions#

_reaction_sign(reaction) → float

Return the orientation a reaction is examined in.

_is_reversible(reaction) → bool

Return whether a reaction can carry flux in its reverse orientation.

_find_flux_mode(model, rxn_ids, signs, flux_threshold, ...) → Set[str]

Perform one of the two LPs required for SPECTRA.

_subset_model(model, keep_ids) → cobra.core.Model

Return a new model holding only the given reactions.

_find_consistent_reaction_ids(model[, tol, ...]) → Tuple[Set[str], int]

Find the flux consistent reactions of a model using SPECTRA [1]_.

spectra_cc(model[, tol, zero_cutoff, seed]) → cobra.core.Model

Check consistency of a metabolic network using SPECTRA [1]_.

Module Contents#

cobra.flux_analysis.spectra_cc.logger#
cobra.flux_analysis.spectra_cc.WEIGHT_RANGE = (1.0, 1.1)#
cobra.flux_analysis.spectra_cc._reaction_sign(reaction: cobra.core.Reaction) → float[source]#

Return the orientation a reaction is examined in.

Reactions that can only carry negative flux are examined in their reverse orientation, which is equivalent to negating their column in the stoichiometric matrix. Every other reaction is examined as is.

Parameters:

reaction (cobra.Reaction) – The reaction to orient.

Returns:

-1.0 if the reaction can only carry negative flux, 1.0 otherwise.

Return type:

float

cobra.flux_analysis.spectra_cc._is_reversible(reaction: cobra.core.Reaction) → bool[source]#

Return whether a reaction can carry flux in its reverse orientation.

Reversibility is evaluated after orienting the reaction as described in _reaction_sign(), so a reaction restricted to negative flux counts as irreversible.

Parameters:

reaction (cobra.Reaction) – The reaction to inspect.

Returns:

Whether the oriented reaction has a negative lower bound.

Return type:

bool

cobra.flux_analysis.spectra_cc._find_flux_mode(model: cobra.core.Model, rxn_ids: Iterable[str], signs: Dict[str, float], flux_threshold: float, zero_cutoff: float, rng: numpy.random.Generator, reverse: bool = False) → Set[str][source]#

Perform one of the two LPs required for SPECTRA.

An auxiliary variable is tied to each given reaction’s oriented flux by a one-sided constraint, and a randomly weighted sum of those auxiliary variables is pushed as far as the flux bounds allow. The randomized weights break ties between reactions, so that repeated calls explore different corners of the optimal face.

The auxiliary variables are free on the side they are pushed away from, rather than held by a large finite bound. A finite bound would quietly become binding on a model whose flux bounds exceed it.

Parameters:
  • model (cobra.Model) – The model to operate on.

  • rxn_ids (iterable of str) – The reactions to drive towards the flux threshold.

  • signs (dict of {str: float}) – The orientation of every reaction, keyed by reaction identifier.

  • flux_threshold (float) – The magnitude the auxiliary variables, and hence the reaction fluxes, are driven to.

  • zero_cutoff (float) – The cutoff below which a flux is considered zero.

  • rng (numpy.random.Generator) – The random generator supplying the objective coefficients.

  • reverse (bool, optional) – Whether to drive the reactions towards negative oriented flux instead (default False).

Returns:

The identifiers of the reactions carrying flux above the cutoff.

Return type:

set of str

cobra.flux_analysis.spectra_cc._subset_model(model: cobra.core.Model, keep_ids: Set[str]) → cobra.core.Model[source]#

Return a new model holding only the given reactions.

The model is built from the reactions that are kept rather than copied whole and then cut down. Deleting is quadratic: each removal makes optlang.Container._reindex rebuild the whole name-to-index map, and the solver is updated once per reaction. Building instead is linear in what is kept, and populates the solver in a single batch.

Parameters:
  • model (cobra.Model) – The model to take the subset of. It is left unchanged.

  • keep_ids (set of str) – The identifiers of the reactions to keep.

Returns:

A new model carrying the kept reactions and everything attached to them, in the order the source had them.

Return type:

cobra.Model

cobra.flux_analysis.spectra_cc._find_consistent_reaction_ids(model: cobra.core.Model, tol: float = 0.0001, zero_cutoff: float | None = None, seed: int | None = None) → Tuple[Set[str], int][source]#

Find the flux consistent reactions of a model using SPECTRA [1]_.

Parameters:
  • model (cobra.Model) – The model to operate on.

  • tol (float, optional) – The flux threshold to consider, i.e. the magnitude the LPs drive the reaction fluxes to (default 1e-4).

  • zero_cutoff (float, optional) – The cutoff below which a flux is considered zero (default model.tolerance).

  • seed (int, optional) – A seed for the random objective coefficients, making the result reproducible (default None).

Returns:

The identifiers of the consistent reactions and the number of LPs that were solved to find them.

Return type:

tuple of (set of str, int)

References

cobra.flux_analysis.spectra_cc.spectra_cc(model: cobra.core.Model, tol: float = 0.0001, zero_cutoff: float | None = None, seed: int | None = None) → cobra.core.Model[source]#

Check consistency of a metabolic network using SPECTRA [1]_.

SPECTRA’s consistency check is a pure LP method for removing the blocked reactions of a metabolic network. Like FASTCC it drives as many reactions as possible towards a flux threshold at once, but it handles reversible reactions without flipping them: the auxiliary variable of the forward LP is unbounded from below, so a reaction that can only carry negative flux simply does not contribute to that LP, and is picked up by the reverse LP instead. The two LPs alternate until the set of unexplained reactions stops shrinking. For more details, please check [1]_.

Parameters:
  • model (cobra.Model) – The model to operate on.

  • tol (float, optional) – The flux threshold to consider, i.e. the magnitude the LPs drive the reaction fluxes to (default 1e-4).

  • zero_cutoff (float, optional) – The cutoff below which a flux is considered zero (default model.tolerance).

  • seed (int, optional) – A seed for the random objective coefficients, making the result reproducible (default None).

Returns:

The consistent model.

Return type:

cobra.Model

Notes

The pair of LPs used for SPECTRA is like so: maximize: sum_{i in J} w_i z_i s.t. : z_i in [-infty, varepsilon] forall i in J

v_i ge z_i forall i in J Sv = 0, v in B

minimize: sum_{i in J^{rev}} w_i z_i s.t. : z_i in [-varepsilon, infty] forall i in J^{rev}

v_i le z_i forall i in J^{rev} Sv = 0, v in B

where \(J\) are the reactions not yet shown to carry flux, \(J^{rev}\) the reversible ones among them, and \(w_i\) are coefficients drawn uniformly from [1, 1.1].

A reaction is taken to be consistent as soon as it carries a flux above zero_cutoff in any of these LPs, which is the same criterion fastcc() applies, so both functions agree on which reactions are blocked. The reference MATLAB implementation instead requires a reaction to reach the flux threshold itself; pass zero_cutoff=0.99 * tol to reproduce that, at the cost of also discarding reactions that can carry some flux but never as much as tol.

References