Top-level (Python)#
raven-toolbox objects in raven_toolbox.
Functions#
Function |
Summary |
|---|---|
Run every applicable confidence scorer in one call; return |
|
Whether lazy first-use downloads are allowed. |
|
Outcome of provisioning one executable. |
|
Remove one facet ( |
|
A |
|
One facet's confidence: a continuous |
|
Download (if needed) and return the path to a bundled |
|
Download (if needed) and return the cached path to one artefact file. |
|
Ensure the core KEGG artefacts are cached; return their directory. |
|
Ensure a domain HMM library is cached and decompressed; return the |
|
Ensure the KEGG |
|
Why |
|
Return the executables in a named set ( |
|
A |
|
Why |
|
Read a reaction's |
|
Load a manifest and merge it into the live data and binary registries. |
|
Read and validate a manifest from |
|
Parse CLI arguments and provision the requested binaries. |
|
Mark a facet as curator-verified: score 1.0, |
|
Return the |
|
Ensure each executable is available, reporting per-tool outcomes. |
|
A reaction's confidence across facets ( |
|
Map each annotated reaction id to its |
|
Resolve an executable to a path: arg → env var → PATH → bundled ZIP → error. |
|
Attach an |
|
Attach a |
|
Attach a |
|
Store one facet's |
|
The reaction's Thiele & Palsson reconstruction confidence score (0-4), or |
|
Project |
|
Project |
Reference#
annotate_confidence#
annotate_confidence(model: cobra.Model, *, proposal: Any=None, scores: Any=None, facets: Iterable[str] | None=None, overwrite_curated: bool=False, updated: str | None=None)
Run every applicable confidence scorer in one call; return {facet: reactions_scored}.
equation and gene_association need only the model and run when requested;
localization runs only when both proposal (an
raven_toolbox.localization.AssignmentProposal) and scores (a
raven_toolbox.localization.LocalizationScores) are given, and is skipped otherwise
without an error, so a caller without a localisation proposal still gets the other two facets.
facets=[...] restricts the run to a subset (names outside the facet set are ignored); by
default all three facets are requested. overwrite_curated and updated are passed to each
scorer.
autofetch_enabled#
autofetch_enabled()
Whether lazy first-use downloads are allowed.
On by default (the zero-setup behaviour). Set RAVEN_PYTHON_AUTOFETCH to
0, false, no or off (any case) to disable, so resolve_binary
stops at PATH and never reaches the network. This suits air-gapped or
conda-managed or system-managed setups.
BinaryStatus#
Outcome of provisioning one executable.
status is one of "present" (already on PATH / via env var),
"downloaded" (fetched from a bundle in this call), "unavailable" (no bundle
hosted for this OS and architecture; install via conda or WSL2), or "error" (download or
verification failed). detail is the path for the statuses "present" and
"downloaded" and a message otherwise.
clear_confidence#
clear_confidence(reaction: cobra.Reaction, facet: str | None=None)
Remove one facet (facet=...) or the whole record (facet=None) from the notes.
confidence_report#
confidence_report(model: cobra.Model)
A pandas.DataFrame of confidence: one row per annotated reaction, a reaction
column, one column per facet score, and overall (the weakest facet). Rows are sorted by
overall, lowest first.
ConfidenceEntry#
One facet's confidence: a continuous score in [0, 1] plus optional provenance.
level is an optional categorical band ("curated", "strong", "moderate",
"weak" or "none"); basis names the evidence ("deeploc",
"deeploc+fba-certified", "balanced", "mass-imbalanced", "gpr+literature",
"curator", ...); source distinguishes "auto" from "curator:<id>".
ensure_binary#
ensure_binary(executable: str, *, registry: dict | None=None)
Download (if needed) and return the path to a bundled executable.
Consults the registry for the current platform, downloads the pinned ZIP,
verifies its SHA256, extracts it into the cache, and returns the executable
path. Raises FileNotFoundError if no bundle for this platform is hosted.
Pass registry to consult an alternate bundle registry in place of the
built-in one (mainly for tests or a custom manifest).
ensure_data_file#
ensure_data_file(dataset: str, filename: str, *, version: str | None=None, registry: dict | None=None, verify: bool=False)
Download (if needed) and return the cached path to one artefact file.
Looks the file up in the registry for dataset (at version or the
registry's default), downloads it to the version-pinned cache directory,
verifies its SHA256, and returns the path. Reuses an already-cached copy.
A freshly downloaded file is always SHA256-checked. verify additionally
re-checks the SHA256 of an already-cached file (a mismatch means a corrupted cache, and
the file is discarded and downloaded again); it is off by default, so a cache hit does
not compute the hash.
ensure_kegg_data#
ensure_kegg_data(*, version: str | None=None, registry: dict | None=None)
Ensure the core KEGG artefacts are cached; return their directory.
Fetches the single <version>_core.tar.gz bundle (the gene-free reference
model + the KO, reaction and organism-gene tables of CORE_KEGG_FILES),
SHA256-verifies it, and extracts the version-prefixed members into the cache
directory on first use. The returned directory can be passed as the artefact_dir of
get_kegg_model_for_organism_from_artefacts. The HMM libraries and the
taxonomy file are separate artefacts (see ensure_kegg_hmm_library,
ensure_kegg_taxonomy).
ensure_kegg_hmm_library#
ensure_kegg_hmm_library(domain: str, *, version: str | None=None, registry: dict | None=None)
Ensure a domain HMM library is cached and decompressed; return the .hmm path.
domain is "prokaryotes" or "eukaryotes". Fetches the gzipped
concatenated library <version>_<domain>.hmm.gz and decompresses it once
(cached). Returns the path to the .hmm flatfile, which is the argument for
run_hmmsearch; it searches the flatfile directly, without hmmpress.
The gzip flatfile is ~10x smaller than a binary index, is portable across HMMER versions and platforms, and serves MATLAB RAVEN as well.
ensure_kegg_taxonomy#
ensure_kegg_taxonomy(*, version: str | None=None, registry: dict | None=None)
Ensure the KEGG taxonomy artefact is cached; return its (gzipped) path.
The gzipped KEGG taxonomy file is the source for domain classification and for
regenerating the phylogenetic distance matrix (RAVEN's keggPhylDist, which GECKO
uses to pick the closest organism for kcat assignment) via
raven_toolbox.reconstruction.kegg.phyl_dist, which reads .gz directly. That
capability needs only this published artefact and no MATLAB .mat file.
equation_exempt#
equation_exempt(reaction: cobra.Reaction)
Why equation does not apply to reaction (a reason string), or None if it does.
Exchange, demand and sink reactions (reaction.boundary, that is any
single-metabolite reaction) exchange mass with the environment; biomass (SBO:0000629)
and pool and SLIME pseudo-reactions (SBO:0000395) are lumped by construction. All are
imbalanced by design and are not scored.
ATP maintenance (SBO:0000630) is not exempt from equation: it is real chemistry
(ATP + H2O -> ADP + Pi + H) and must balance. It is exempt from gene_association,
because it has no catalyst. See gene_association_exempt.
executables_for_set#
executables_for_set(set_name: str)
Return the executables in a named set ("all" = the union of every set).
facet_summary#
facet_summary(model: cobra.Model)
A pandas.DataFrame of reaction counts per facet, basis, score and level.
The column n holds the count. Only scored reactions are counted, because a reaction to which
a facet does not apply has no entry for it. The share of the model whose chemistry is verified
balanced follows from the rows with facet == "equation" and basis == "balanced".
gene_association_exempt#
gene_association_exempt(reaction: cobra.Reaction)
Why gene_association does not apply to reaction (a reason string), or None.
Everything equation_exempt excludes, plus the reactions that have no catalyst by
definition: ATP maintenance (SBO:0000630) and spontaneous reactions (SBO:0000672,
defined as "reaction with no catalyst ... is needed to proceed"). Transport (SBO:0000655) is
not exempt: the term is defined as movement "mediated by a transporter protein", so a transport
reaction with no transporter gene is a curation gap.
get_confidence#
get_confidence(reaction: cobra.Reaction)
Read a reaction's ReactionConfidence from its notes (empty if absent or unreadable).
Accepts a native dict (YAML and JSON models) and a JSON string (SBML, possibly HTML-escaped).
load_into_registries#
load_into_registries(source: str | os.PathLike | None=None, *, replace: bool=False)
Load a manifest and merge it into the live data and binary registries.
Parameters
sourceManifest path or URL; defaults to
$RAVEN_PYTHON_MANIFEST.replaceIf True, clear the existing registries first; otherwise merge; on a conflict the manifest entry replaces the registry entry.
Returns
dictThe parsed manifest.
load_manifest#
load_manifest(source: str | os.PathLike | None=None)
Read and validate a manifest from source (path or URL) or $RAVEN_PYTHON_MANIFEST.
main#
main(argv: list[str] | None=None)
Parse CLI arguments and provision the requested binaries.
Prints a per-tool status line and returns the process exit code: 1 if any
download failed, otherwise 0 (tools reported as unavailable do not change the
exit code).
mark_curated#
mark_curated(reaction: cobra.Reaction, *, facet: str='localization', source: str='curator', note: str | None=None, updated: str | None=None)
Mark a facet as curator-verified: score 1.0, level="curated".
Records a curator's decision on a reaction (for example its compartment, set via
raven_toolbox.localization.relocate_reactions), so the decision persists in the model
and the automated scorer for that facet leaves it untouched on a later pass unless the
scorer is called with overwrite_curated=True.
An equation facet of a reaction whose chemistry is verified balanced also scores 1.0.
Automated gene_association scores are at most 0.9; an automated localization score
equals the DeepLoc support.
platform_key#
platform_key()
Return the <os>-<arch> key used in the registry (for example linux-x86_64).
provision_binaries#
provision_binaries(executables: tuple[str, ...] | list[str], *, registry: dict | None=None, prefer_existing: bool=True)
Ensure each executable is available, reporting per-tool outcomes.
With prefer_existing (default) a tool already on PATH or pointed at by its
env var is left as-is ("present") and not downloaded. Otherwise the bundle
is fetched via ensure_binary (registry, if given, is forwarded to
it in place of the built-in registry). A missing platform bundle is recorded as
"unavailable" and a failed download as "error", so a caller can report the
whole set at once.
ReactionConfidence#
A reaction's confidence across facets ({facet_name: ConfidenceEntry}).
read_confidence#
read_confidence(model: cobra.Model)
Map each annotated reaction id to its ReactionConfidence (others omitted).
resolve_binary#
resolve_binary(executable: str, *, binary: str | os.PathLike | None=None)
Resolve an executable to a path: arg → env var → PATH → bundled ZIP → error.
The bundled-ZIP step is skipped when auto-fetch is disabled
(autofetch_enabled); resolution then stops at PATH and raises an actionable
error without downloading.
score_equation_confidence#
score_equation_confidence(model, *, overwrite_curated: bool=False, updated: str | None=None, tolerance: float=_CHARGE_TOL)
Attach an equation confidence (mass and charge balance) to every applicable reaction.
Returns the number of reactions scored. Reactions that equation_exempt excludes are not
scored: an exchange reaction is imbalanced by construction, and writing 1.0 there would make
469 never-checked yeast-GEM reactions indistinguishable from the 3617 verified ones.
Bands, lowest first: a proven mass imbalance (0.0); a proven charge imbalance (0.1,
above the mass imbalance because a charge difference can come from a protonation-state
convention of the formulas); a formula missing, unparseable, or generic (0.3,
unverifiable); mass proven but charge unset (0.6); balanced (1.0).
tolerance is the absolute net-charge threshold up to which a reaction counts as
charge-balanced.
score_gene_association_confidence#
score_gene_association_confidence(model, *, overwrite_curated: bool=False, updated: str | None=None)
Attach a gene_association confidence to every applicable reaction; return the count.
Bands: no GPR (0.2); a GPR (0.6); a GPR plus a literature citation, that is a pubmed
annotation (0.9). These correspond to the Thiele-Palsson levels 0 and 1, 2, and 3. The
scoring reads only the GPR and the citation, so a model's recorded Confidence Level note is
not an input and remains an independent check of the scores.
1.0 is set only by mark_curated. Reactions that gene_association_exempt
excludes (boundary, biomass, pseudo-reaction, maintenance, spontaneous) are not scored;
transport reactions are scored.
score_localization_confidence#
score_localization_confidence(model, proposal, scores, *, overwrite_curated: bool=False, updated: str | None=None)
Attach a localization confidence to the placements in proposal; return the count.
The score is the DeepLoc support for the assigned compartment (the highest score of any of the
reaction's genes there), so 0.0 means the evidence places the reaction in another
compartment. The basis records deeploc and, when the proposal is certified,
fba-certified.
A reaction whose genes are absent from scores (placed by connectivity alone) is not scored:
no measurement was possible, and writing 0.0 would lower the reaction's overall because
of a missing input and not because of evidence. Such reactions are covered by their
gene_association facet and by the no_evidence signal of
raven_toolbox.localization.curation_priority. Placements already marked curated are
left unchanged unless overwrite_curated is true.
The score is the inverse of the localisation signal in curation_priority: high confidence
here corresponds to low review priority there. model is the draft the proposal was built on.
set_confidence#
set_confidence(reaction: cobra.Reaction, facet: str, entry: ConfidenceEntry)
Store one facet's ConfidenceEntry in the reaction's record, keeping other facets.
thiele_palsson_score#
thiele_palsson_score(reaction: cobra.Reaction)
The reaction's Thiele & Palsson reconstruction confidence score (0-4), or None.
Derived from the gene_association facet's basis
(score_gene_association_confidence), the facet that records reaction-inclusion evidence:
gpr+literature -> 3 (experimental or genetic), gpr -> 2 (sequence), no-gpr -> 1
(modelling). Returns None when the facet is absent (the reaction was not scored, or
gene_association does not apply to it) or has any other basis, including curator
(the evidence class of a curated entry is set by the curator; see the module note and the study
doc §9). The localization and equation facets are quality checks and are not consulted.
to_binary_registry#
to_binary_registry(manifest: dict)
Project manifest['binaries'] onto the raven_toolbox.binaries._REGISTRY shape.
to_data_registry#
to_data_registry(manifest: dict)
Project manifest['data'] onto the raven_toolbox.data._DATA_REGISTRY shape.