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. |
|
Drop 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/binary registries. |
|
Read and validate a manifest from |
|
Parse CLI arguments and provision the requested binaries. |
|
Stamp a facet as curator-verified: confidence 1.0, |
|
Return the |
|
Ensure each executable is available, reporting per-tool outcomes. |
|
A reaction's confidence across facets ( |
|
Every annotated reaction id -> its |
|
Resolve an executable to a path: arg → env var → PATH → bundled ZIP → error. |
|
Attach an |
|
Attach a |
|
Attach a |
|
Merge 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 always run; localization runs
only when both proposal (an raven_toolbox.localization.AssignmentProposal) and
scores (a raven_toolbox.localization.LocalizationScores) are given, and is otherwise
skipped rather than failing — the same abstain-rather-than-guess rule the scores follow, so a
caller without a localisation proposal still gets the other two facets. facets=[...] restricts
to a subset (names outside the facet set are ignored). overwrite_curated and updated pass
through 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/off (any case) to disable, so resolve_binary
stops at PATH and never reaches the network — for air-gapped or
strictly conda/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 just now), "unavailable" (no bundle
hosted for this OS/arch — install via conda/WSL2), or "error" (download or
verification failed). detail is the path (present/downloaded) or message.
clear_confidence#
clear_confidence(reaction: cobra.Reaction, facet: str | None=None)
Drop one facet (facet=...) or the whole record (facet=None) from the reaction's notes.
confidence_report#
confidence_report(model: cobra.Model)
A pandas.DataFrame of confidence: one row per annotated reaction, one column per facet
score, plus overall (the weakest facet). Sorted lowest-confidence first — the review queue.
ConfidenceEntry#
One facet's confidence: a continuous score in [0, 1] plus optional provenance.
level is an optional categorical band ("curated" / "strong" / "moderate" / "weak"
/ "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 instead 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. Re-uses an already-cached copy.
A freshly downloaded file is always SHA256-checked. verify additionally
re-checks an already-cached file's SHA256 (a mismatch — i.e. a corrupted
cache — discards it and re-downloads); it is off by default so the common
cache-hit path stays fast.
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/organism-gene tables of CORE_KEGG_FILES),
SHA256-verifies it, and extracts the version-prefixed members into the cache
directory on first use — ready to pass 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 — the argument for
run_hmmsearch, which searches it directly (no hmmpress needed).
Shipping the gzip flatfile keeps the download ~10x smaller than a binary index, stays portable across HMMER versions/platforms, and lets the same artefact serve MATLAB RAVEN.
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). So
that capability needs only this published artefact, 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/sink reactions (reaction.boundary, i.e. any single-metabolite reaction) exchange
mass with the environment; biomass (SBO:0000629) and pool/SLIME pseudo-reactions
(SBO:0000395) are lumped by construction. All are imbalanced by design, so their chemistry is
not a defect and must not be scored.
ATP maintenance (SBO:0000630) is deliberately not exempt: it is real chemistry
(ATP + H2O -> ADP + Pi + H) and must balance. It is exempt from gene_association instead —
real chemistry, 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 facet × basis × score counts over the model.
The audit trail abstention leaves behind: it separates scored reactions from the ones no facet applies to, so "the fraction of this model whose chemistry is verified balanced" is a number you can read off rather than infer from a score column.
gene_association_exempt#
gene_association_exempt(reaction: cobra.Reaction)
Why gene_association does not apply to reaction (a reason string), or None if it does.
Everything equation_exempt excludes, plus the reactions that legitimately have no catalyst:
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 genuine curation gap, not a modelling convention.
get_confidence#
get_confidence(reaction: cobra.Reaction)
Read a reaction's ReactionConfidence from its notes (empty if none / unreadable).
Handles both a native dict (YAML/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/binary registries.
Parameters
sourceManifest path or URL; defaults to
$RAVEN_PYTHON_MANIFEST.replaceIf True, clear the existing registries first; otherwise merge (manifest wins).
Returns
dictThe parsed manifest.
load_manifest#
load_manifest(source: str | os.PathLike | None=None)
Read and validate a manifest from source (path/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: 0 if
every tool ended up present or downloaded, 1 if any download failed.
mark_curated#
mark_curated(reaction: cobra.Reaction, *, facet: str='localization', source: str='curator', note: str | None=None, updated: str | None=None)
Stamp a facet as curator-verified: confidence 1.0, level="curated".
Call after a curator firmly fixes a reaction (e.g. its compartment, 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.
1.0 is reserved for this and for a proven check (a reaction whose chemistry is verified
balanced); the evidence-derived bands cap at 0.9, so a curated call always outranks an inferred one.
platform_key#
platform_key()
Return the <os>-<arch> key used in the registry (e.g. 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). Never raises for an individual tool —
a missing platform bundle becomes "unavailable" and a failed download
"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)
Every annotated reaction id -> its ReactionConfidence (reactions with no record 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 with an actionable
error instead of 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 & charge balance) to every applicable reaction.
Returns the number of reactions scored. Reactions 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, a rung
up because it is usually a protonation convention); a formula missing, unparseable, or generic
(0.3 — unverifiable, not wrong); mass proven but charge unset (0.6); balanced (1.0).
tolerance is the absolute net-charge threshold below which a reaction counts as
charge-balanced rather than charge-imbalanced.
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 scored.
Bands: no GPR (0.2); a GPR (0.6); a GPR plus a literature citation, i.e. a pubmed
annotation (0.9). These mirror the Thiele-Palsson levels 0/1, 2 and 3 — and because the rubric
reads only the GPR and the citation, a curated model's own recorded Confidence Level note is
left free to serve as an independent check of it rather than as an input.
1.0 is reserved for mark_curated. Reactions gene_association_exempt excludes
(boundary, biomass, pseudo, maintenance, spontaneous) are not scored; transport reactions are.
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 and return the count scored.
The score is the DeepLoc support for the assigned compartment (the strongest scored gene's score
there), so 0.0 means the evidence actively puts the reaction elsewhere. 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 veto the reaction's overall on the
strength of a missing input rather than of evidence. Such reactions surface through their
gene_association facet and through
raven_toolbox.localization.curation_priority's no_evidence signal instead. Placements
already marked curated are left alone unless overwrite_curated.
This is the inverse of the localization signal in curation_priority: high confidence here ==
low review priority there. model is the draft the proposal was built on.
set_confidence#
set_confidence(reaction: cobra.Reaction, facet: str, entry: ConfidenceEntry)
Merge one facet's ConfidenceEntry into the reaction's record and persist it to notes.
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 captures reaction-inclusion evidence: gpr+literature -> 3 (experimental/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 curated (whose evidence
class the curator must name — see the module note and the study doc §9). The localization and
equation facets are quality checks, not Thiele-Palsson evidence classes, 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.