Comparison (Python)#

raven-toolbox objects in raven_toolbox.comparison.

Functions#

Function

Summary

compare_models

Compare N cobra models on their reactions, metabolites, genes, ec_codes,

diff_models

Compare two cobra models for semantic equality.

DiffReport

Result of diff_models.

ModelComparison

Tabular result of compare_models.

Reference#

compare_models#

compare_models(models: Iterable[cobra.Model], *, tasks: str | PathLike[str] | Iterable[Task] | None=None)

Compare N cobra models on their reactions, metabolites, genes, ec_codes,

metabolite_names, equations, equations_no_compartments and subsystems (and tasks, if provided).

Models are identified by model.id. A missing or blank id becomes model_<i> and a repeated id gets the suffix __<n> (__2 for the second occurrence).

Parameters

models : Iterable[cobra.Model]

The models to compare. At least two are required, otherwise ValueError is raised. The models are not modified.

tasks : str or os.PathLike or Iterable[Task] or None

Metabolic tasks, passed to raven_toolbox.tasks.check_tasks for each model. It is a file path (str or os.PathLike) or a parsed task list. When omitted, ModelComparison.tasks is None.

diff_models#

diff_models(a: cobra.Model, b: cobra.Model, *, stoichiometry_tol: float=1e-09, ignore_annotations: Iterable[str]=(), extra_annotations: Iterable[str]=(), max_per_category: int=50)

Compare two cobra models for semantic equality.

Returns a DiffReport that lists every difference found in the following properties:

  • reaction, metabolite and gene id sets (exact)

  • stoichiometry per shared reaction (within stoichiometry_tol)

  • lower and upper bounds and objective coefficients (exact)

  • GPR rules (compared as logic: the rules are expanded to disjunctive normal form, and gene and clause order is ignored)

  • metabolite formula, charge, compartment (exact; an empty formula equals a missing one and a missing charge equals 0)

  • the annotation keys in DEFAULT_ANNOTATION_KEYS plus those in extra_annotations, minus those in ignore_annotations

The GPR comparison lowercases gene ids, so rules that differ only in the case of a gene id are equal. RAVEN's diffModels compares gene ids case-sensitively.

Parameters

a : cobra.Model

First model, labelled A in the difference messages.

b : cobra.Model

Second model, labelled B in the difference messages.

stoichiometry_tol : float

Largest absolute difference between two stoichiometric coefficients that counts as equal. Default 1e-9. Reactions whose metabolite sets differ are reported regardless.

ignore_annotations : Iterable[str]

Annotation keys removed from the compared set. Default: no key removed.

extra_annotations : Iterable[str]

Annotation keys compared in addition to DEFAULT_ANNOTATION_KEYS. Default: no additional key. For every compared key, default or extra, values are compared as sorted tuples of strings when they are lists or tuples, otherwise as strings.

max_per_category : int

Maximum number of differences reported per category. The categories are stoichiometry, bounds, objective, GPR and annotation for reactions, and formula, charge, compartment and annotation for metabolites; the annotation category counts the differences of all compared annotation keys together. The first difference beyond the cap adds one entry that reports the truncation. Default 50. The lists of ids that are present in only one model are not capped by this value; each shows 10 ids.

DiffReport#

Result of diff_models.

Truthy if the models are semantically equal. Iterate differences for human-readable messages.

ModelComparison#

Tabular result of compare_models.

All matrices (reactions, metabolites, genes, ec_codes, metabolite_names, equations, equations_no_compartments and subsystems) are indexed by id or value with one column per model. The presence matrices are 0/1; subsystems is the per-model reaction count per subsystem. similarity is the model × model Jaccard on the reaction set (1 = identical, 0 = disjoint). tasks is the per-model task pass-or-fail matrix (None unless task checking was requested); failed_tasks maps each model id to the failure messages for the tasks it did not pass.

equations and equations_no_compartments key each reaction by a canonical string built from its metabolites and stoichiometry: sides are sorted, and for a reversible reaction the side whose first sorted entry is lexicographically smaller is written as the reactant side. Two reactions that differ only in metabolite order or, for reversible reactions, in direction compare equal. equations keeps compartments in each metabolite id; equations_no_compartments strips them.