Utilities (Python)¶

raven-toolbox objects in raven_toolbox.utils, collected from the source of the tracked branch.

Functions¶

Function	Summary
`check_model`	Run curation checks on a model and return the issues found.
`ElementalBalance`	Balance result for one reaction.
`find_non_dnf_grrules`	Find reactions whose GPR is not in disjunctive normal form ("OR of AND-complexes").
`get_elemental_balance`	Check whether reactions are elementally balanced.
`GPRIssue`	A reaction whose GPR is flagged by the linter.
`is_dnf`	Return whether a GPR is in disjunctive normal form (OR of AND-complexes).
`ModelIssue`	One curation issue found in a model.
`parse_name_comp`	Split a `name[comp]` token into `(name, compartment)`.
`resolve_aggregators`	Validate the scoring-mode names and return `(isozyme_fn, complex_fn)`.
`sort_identifiers`	Sort reactions, metabolites and genes alphabetically by ID, in place.
`subsystem_to_str`	Coerce a reaction `subsystem` to cobra's canonical `str` form.

Reference¶

check_model¶

Run curation checks on a model and return the issues found.

Does not raise; returns a (possibly empty) list of :class:ModelIssue.

ElementalBalance¶

Balance result for one reaction.

Attributes:

Name	Type	Description
`reaction_id`	`str`	ID of the reaction.
`status`	`str`	`"balanced"` — elements balance; `"unbalanced"` — they do not (see `imbalance`); `"unknown"` — at least one metabolite has no formula, so it cannot be determined (cobra would silently miscount these).
`imbalance`	`dict[str, float]`	Element → net coefficient (products − reactants), only for `"unbalanced"`; empty otherwise. Charge is not included.

find_non_dnf_grrules¶

Find reactions whose GPR is not in disjunctive normal form ("OR of AND-complexes").

Uses cobra's GPR AST. Reactions with no GPR are skipped.

Returns:

Type	Description
`list of GPRIssue`	One entry per flagged reaction, in model reaction order. Empty if all GPRs are simple OR-of-AND-complexes.

get_elemental_balance¶

Check whether reactions are elementally balanced.

Parameters:

Name	Type	Description	Default
`reactions`		Reaction IDs/objects to check; default all reactions. (Boundary reactions exchange mass with the environment and will read as `unbalanced` — filter them out if that is not wanted.)	`None`

Returns:

Type	Description
`list of ElementalBalance`	One entry per checked reaction, in model order.

GPRIssue¶

A reaction whose GPR is flagged by the linter.

Attributes:

Name	Type	Description
`reaction_id`	`str`	ID of the reaction.
`gpr`	`str`	The (already cobra-normalised) grRule string.
`reason`	`str`	Human-readable explanation of why it was flagged.

is_dnf¶

Return whether a GPR is in disjunctive normal form (OR of AND-complexes).

Parameters:

Name	Type	Description	Default
`gpr`	`GPR \| str \| None`	A cobra :class:`~cobra.core.gene.GPR`, a grRule string, or `None`. An empty/`None` rule is trivially DNF.	required

Examples:

>>> is_dnf("(G1 and G2) or G3")
True
>>> is_dnf("(G1 or G2) and G3")
False

ModelIssue¶

One curation issue found in a model.

Attributes:

Name	Type	Description
`category`	`str`	Machine-readable kind, e.g. `"orphan_metabolite"`, `"empty_reaction"`, `"orphan_gene"`, `"duplicate_name_compartment"`, `"empty_metabolite_name"`, `"objective"`.
`object_id`	`str \| None`	ID of the offending object, or `None` for model-level issues.
`message`	`str`	Human-readable description.

parse_name_comp¶

Split a name[comp] token into (name, compartment).

This is the one genuinely cobra-absent sliver of RAVEN getIndexes' metcomps mode and addRxns eqnType 3: resolving a metabolite written as its name plus a compartment in square brackets, e.g. "ATP[c]".

Returns (name, None) when there is no trailing [...].

Examples:

>>> parse_name_comp("ATP[c]")
('ATP', 'c')
>>> parse_name_comp("ATP")
('ATP', None)
>>> parse_name_comp("weird[name][m]")
('weird[name]', 'm')

resolve_aggregators¶

Validate the scoring-mode names and return (isozyme_fn, complex_fn).

Raises ValueError naming the offending argument if either mode is not one of :data:AGGREGATORS.

sort_identifiers¶

Sort reactions, metabolites and genes alphabetically by ID, in place.

Returns the same (mutated) model for convenience. Compartments are a plain dict and are emitted sorted by writers as needed.

subsystem_to_str¶

Coerce a reaction subsystem to cobra's canonical str form.

cobra defines Reaction.subsystem as a plain string, but RAVEN/MATLAB and "messy" YAML sometimes deliver a list/tuple of subsystem names (a reaction can belong to several). This collapses any such value to a single ;-joined string of its parts — losing no data, unlike taking only the first — and returns "" for an empty/None subsystem. Used wherever a subsystem is rendered or compared so the handling is identical across modules.

Examples:

>>> subsystem_to_str("glycolysis")
'glycolysis'
>>> subsystem_to_str(["glycolysis", "TCA cycle"])
'glycolysis;TCA cycle'
>>> subsystem_to_str(None)
''