raven-toolbox 0.2.0__py3-none-any.whl

raven_toolbox/__init__.py

@@ -0,0 +1,15 @@
+"""raven_toolbox — Python counterpart of the RAVEN Toolbox, built on cobrapy.
+
+raven_toolbox reuses cobrapy for simulation, standard analyses, SBML I/O, and model
+manipulation, and provides the RAVEN-specific functionality on top: de novo
+reconstruction (KEGG / homology), context-specific modeling (tINIT / ftINIT),
+metabolic task validation, connectivity gap-filling, omics integration (HPA),
+sub-cellular localisation, N-model comparison, and the RAVEN-style I/O formats.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("raven-toolbox")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"

raven_toolbox/analysis/__init__.py

@@ -0,0 +1,23 @@
+"""Analyses not in cobrapy's core.
+
+* :func:`reporter_metabolites` — Reporter Metabolites (around-metabolite gene-score test).
+* :func:`fseof` — Flux Scanning based on Enforced Objective Flux.
+* :func:`random_sampling` — random-objective flux sampling.
+"""
+from raven_toolbox.analysis.fseof import FSEOFResult, fseof
+from raven_toolbox.analysis.reporter import ReporterResult, reporter_metabolites
+from raven_toolbox.analysis.sampling import (
+    RandomSamplingResult,
+    find_good_reactions,
+    random_sampling,
+)
+
+__all__ = [
+    "FSEOFResult",
+    "RandomSamplingResult",
+    "ReporterResult",
+    "find_good_reactions",
+    "fseof",
+    "random_sampling",
+    "reporter_metabolites",
+]

raven_toolbox/analysis/fseof.py

@@ -0,0 +1,161 @@
+"""Flux Scanning based on Enforced Objective Flux — FSEOF (port + redesign).
+
+FSEOF (Choi et al., Appl Environ Microbiol 2010) finds metabolic-engineering targets
+for over-producing a metabolite: enforce an increasing flux toward the target product
+while optimising growth, and watch how each reaction's flux responds. This is a port
+of RAVEN's ``FSEOF`` with a substantially richer, more robust output (RAVEN's
+weaknesses are noted in IMPROVEMENTS, FS1–FS4):
+
+* **Robust trend, not strict monotonicity.** Each reaction's flux is regressed against
+  the enforced product flux across the scan; the **slope** is the response and the
+  **correlation** (|r|) is a quality score. A reaction is a target if it tracks the
+  product cleanly (|r| ≥ ``correlation_threshold``) — one noisy step from LP
+  alternative optima no longer discards it (and pFBA per step keeps the scan stable).
+* **Direction classification RAVEN lacks.** Targets are labelled ``amplify`` (|flux|
+  rises with the product → over-express), ``knockdown`` (|flux| falls), or ``knockout``
+  (|flux| → ~0 → delete). RAVEN only ever reports the amplification targets.
+* **Gene-level view** via :attr:`FSEOFResult.gene_targets`, and the full flux scan is
+  retained in :attr:`FSEOFResult.scan` — all as DataFrames, not a printed TSV.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import cobra
+import numpy as np
+import pandas as pd
+from cobra.exceptions import OptimizationError
+from cobra.flux_analysis import pfba
+from scipy.stats import linregress
+
+
+@dataclass
+class FSEOFResult:
+    """FSEOF output.
+
+    ``scan`` is reactions × enforced-flux-levels (the full flux scan); ``enforced`` are
+    the enforced target fluxes; ``targets`` is the classified per-reaction table
+    (sorted by score). :attr:`gene_targets` aggregates targets to genes.
+    """
+
+    scan: pd.DataFrame
+    enforced: list[float]
+    targets: pd.DataFrame
+
+    @property
+    def amplification(self) -> pd.DataFrame:
+        return self.targets[self.targets["target_type"] == "amplify"].reset_index(drop=True)
+
+    @property
+    def knockout(self) -> pd.DataFrame:
+        mask = self.targets["target_type"].isin(["knockout", "knockdown"])
+        return self.targets[mask].reset_index(drop=True)
+
+    @property
+    def gene_targets(self) -> pd.DataFrame:
+        """Per-gene aggregation: the target reactions each gene is associated with."""
+        rows = []
+        for _, t in self.targets.iterrows():
+            for gene in t["genes"]:
+                rows.append({"gene": gene, "reaction": t["reaction"],
+                             "target_type": t["target_type"], "slope": t["slope"]})
+        if not rows:
+            return pd.DataFrame(columns=["gene", "target_type", "reactions", "max_abs_slope"])
+        df = pd.DataFrame(rows)
+        agg = df.groupby("gene").agg(
+            target_type=("target_type", lambda s: ";".join(sorted(set(s)))),
+            reactions=("reaction", lambda s: ";".join(sorted(set(s)))),
+            max_abs_slope=("slope", lambda s: float(np.max(np.abs(s)))),
+        ).reset_index()
+        return agg.sort_values("max_abs_slope", ascending=False, ignore_index=True)
+
+
+def fseof(
+    model: cobra.Model,
+    target_rxn: str,
+    *,
+    biomass_rxn: str | None = None,
+    n_steps: int = 10,
+    max_fraction: float = 0.9,
+    correlation_threshold: float = 0.9,
+    flux_eps: float = 1e-6,
+) -> FSEOFResult:
+    """Run FSEOF for over-production of ``target_rxn``'s product.
+
+    Enforces target flux from ``max_fraction/n_steps`` up to ``max_fraction`` of the
+    theoretical maximum in ``n_steps`` steps, maximising growth (``biomass_rxn`` or the
+    model's current objective) with pFBA at each step. Returns an :class:`FSEOFResult`.
+    """
+    with model:  # find the theoretical maximum target flux
+        model.objective = target_rxn
+        target_opt = model.slim_optimize()
+    # slim_optimize returns NaN on an infeasible model; np.isfinite catches that too.
+    if target_opt is None or not np.isfinite(target_opt) or target_opt <= flux_eps:
+        raise ValueError(f"{target_rxn!r} cannot carry positive flux; nothing to scan.")
+    target_max = target_opt * max_fraction
+    levels = [target_max * (i + 1) / n_steps for i in range(n_steps)]
+
+    columns: dict[float, pd.Series] = {}
+    enforced: list[float] = []
+    for level in levels:
+        with model:
+            if biomass_rxn is not None:
+                model.objective = biomass_rxn
+            model.reactions.get_by_id(target_rxn).lower_bound = level
+            try:
+                columns[level] = pfba(model).fluxes
+            except OptimizationError:
+                break  # enforced flux became infeasible — stop scanning
+            enforced.append(level)
+    if len(enforced) < 2:
+        raise RuntimeError("FSEOF needs at least two feasible enforced-flux levels.")
+
+    scan = pd.DataFrame(columns)
+    targets = _classify(model, scan, np.asarray(enforced), correlation_threshold, flux_eps)
+    return FSEOFResult(scan=scan, enforced=enforced, targets=targets)
+
+
+def _classify(model, scan, enforced, corr_threshold, flux_eps) -> pd.DataFrame:
+    rows = []
+    for rxn in model.reactions:
+        flux = scan.loc[rxn.id, enforced.tolist() if hasattr(enforced, "tolist") else enforced]
+        flux = flux.to_numpy(dtype=float)
+        initial, final = flux[0], flux[-1]
+        if flux.std() < flux_eps:  # flat -> no response
+            continue
+        fit = linregress(enforced, flux)
+        slope, corr = float(fit.slope), float(fit.rvalue)
+        if abs(corr) < corr_threshold or abs(slope) < flux_eps:
+            continue
+        # Classify on the slope of |flux| vs the enforced product flux — the
+        # criterion the docstring states (|flux| rises = amplify, etc.). The
+        # old endpoint-only check (``abs(final) vs abs(initial)``) could
+        # mislabel a track whose first/last values straddled a peak/trough but
+        # whose overall trend was the opposite. Keep ``knockout`` for tracks
+        # the regression drives essentially to zero.
+        abs_fit = linregress(enforced, np.abs(flux))
+        abs_slope = float(abs_fit.slope)
+        if abs(final) < flux_eps and abs_slope < 0:
+            ttype = "knockout"
+        elif abs_slope > 0:
+            ttype = "amplify"
+        else:
+            ttype = "knockdown"
+        rows.append({
+            "reaction": rxn.id,
+            "name": rxn.name,
+            "subsystem": rxn.subsystem,
+            "gene_reaction_rule": rxn.gene_reaction_rule,
+            "genes": sorted(g.id for g in rxn.genes),
+            "target_type": ttype,
+            "slope": slope,
+            "correlation": corr,
+            "initial_flux": initial,
+            "final_flux": final,
+            "score": abs(slope) * abs(corr),
+        })
+    table = pd.DataFrame(rows, columns=[
+        "reaction", "name", "subsystem", "gene_reaction_rule", "genes",
+        "target_type", "slope", "correlation", "initial_flux", "final_flux", "score",
+    ])
+    return table.sort_values("score", ascending=False, ignore_index=True)

raven_toolbox/analysis/reporter.py

@@ -0,0 +1,119 @@
+"""Reporter Metabolites — metabolites around which transcriptional change concentrates.
+
+Patil & Nielsen, PNAS 2005. Each gene's differential-expression p-value becomes a
+Z-score ``z = -Φ⁻¹(p)``; for every metabolite the Z-scores of the genes on its
+neighbouring reactions are aggregated (``Σz / √n``), background-corrected, and turned
+back into a p-value.
+
+The background correction has an exact closed form (sampling with replacement from the
+scored-gene pool: a random ``Σz/√n`` has mean ``√n·μ`` and standard deviation ``σ``
+with μ, σ the mean/std of the scored Z-scores), so the corrected score is just
+``(metZ − √n·μ) / σ`` — no Monte-Carlo sampling needed.
+"""
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import cobra
+import numpy as np
+import pandas as pd
+from scipy.stats import norm
+
+_CLAMP = 15.0  # |Z| cap for p-values of exactly 0 or 1 (RAVEN's ±15)
+
+
+@dataclass
+class ReporterResult:
+    """Reporter-metabolite scores for one gene set.
+
+    ``test`` is ``"all"``, ``"up"`` or ``"down"``; ``table`` is a DataFrame with
+    columns ``metabolite, name, z_score, p_value, n_genes, mean_z, std_z`` sorted by
+    descending ``z_score``.
+    """
+
+    test: str
+    table: pd.DataFrame
+
+
+def _gene_z(pvalues: dict[str, float]) -> dict[str, float]:
+    genes = list(pvalues)
+    z = -norm.ppf([pvalues[g] for g in genes])
+    z = np.where(np.isposinf(z), _CLAMP, z)
+    z = np.where(np.isneginf(z), -_CLAMP, z)
+    return dict(zip(genes, z, strict=True))
+
+
+def _reporter_one(model: cobra.Model, gene_z: dict[str, float], test: str) -> ReporterResult:
+    z_values = np.fromiter(gene_z.values(), dtype=float)
+    mu = float(z_values.mean()) if z_values.size else 0.0
+    sigma = float(z_values.std(ddof=0)) if z_values.size else 0.0
+
+    rows = []
+    for met in model.metabolites:
+        neighbours = {g.id for rxn in met.reactions for g in rxn.genes if g.id in gene_z}
+        if not neighbours:
+            continue
+        zs = np.array([gene_z[g] for g in neighbours])
+        n = zs.size
+        raw = zs.sum() / math.sqrt(n)
+        # Exact background correction for sampling-with-replacement (see module doc).
+        corrected = (raw - math.sqrt(n) * mu) / sigma if sigma > 0 else 0.0
+        if not math.isfinite(corrected):  # never on clamped z-scores; guards the p-value
+            corrected = 0.0
+        rows.append(
+            {
+                "metabolite": met.id,
+                "name": met.name or met.id,
+                "z_score": corrected,
+                "p_value": float(1.0 - norm.cdf(corrected)),
+                "n_genes": n,
+                "mean_z": float(zs.mean()),
+                "std_z": float(zs.std(ddof=1)) if n > 1 else float("nan"),
+            }
+        )
+    table = pd.DataFrame(rows, columns=["metabolite", "name", "z_score", "p_value", "n_genes", "mean_z", "std_z"])
+    table = table.sort_values("z_score", ascending=False, ignore_index=True)
+    return ReporterResult(test, table)
+
+
+def reporter_metabolites(
+    model: cobra.Model,
+    gene_pvalues: Mapping[str, float],
+    *,
+    gene_fold_changes: Mapping[str, float] | None = None,
+) -> list[ReporterResult]:
+    """Compute Reporter Metabolites from per-gene differential-expression p-values.
+
+    ``gene_pvalues`` maps gene id → p-value (genes not in the model, or with a NaN or
+    out-of-``[0, 1]`` p-value, are dropped — a stray invalid p-value would otherwise
+    turn the whole result NaN). If ``gene_fold_changes`` (gene id → log fold change)
+    is given, two extra results are returned for the up- (fc ≥ 0) and down- (fc < 0)
+    regulated gene subsets, in addition to ``"all"``.
+
+    Parity with RAVEN's ``reporterMetabolites``: the ``z_score`` and underlying
+    background correction match exactly (exact closed-form instead of RAVEN's
+    Monte-Carlo, see IMPROVEMENTS RM1). The reported ``p_value`` is the
+    *one-sided* (``"up"``) enrichment ``1 - Φ(z)`` and the result is sorted by
+    ``z_score`` descending. RAVEN sorts by p-value and reports both tails
+    (``allPValues``, ``allUpPValues``, ``allDownPValues``); the up/down splits
+    here come from the ``gene_fold_changes`` subset partition instead, so the
+    same information is available via the three returned ``ReporterResult``
+    rows.
+    """
+    model_genes = {g.id for g in model.genes}
+    scored = {
+        g: float(p)
+        for g, p in gene_pvalues.items()
+        if g in model_genes and p is not None and not math.isnan(p) and 0.0 <= p <= 1.0
+    }
+    gene_z = _gene_z(scored)
+    results = [_reporter_one(model, gene_z, "all")]
+
+    if gene_fold_changes is not None:
+        up = {g: z for g, z in gene_z.items() if gene_fold_changes.get(g, 0.0) >= 0}
+        down = {g: z for g, z in gene_z.items() if gene_fold_changes.get(g, 0.0) < 0}
+        results.append(_reporter_one(model, up, "up"))
+        results.append(_reporter_one(model, down, "down"))
+    return results

raven_toolbox/analysis/sampling.py

@@ -0,0 +1,218 @@
+"""Random-objective flux sampling — RAVEN's ``randomSampling`` (port + improvements).
+
+Samples the flux solution space by the **random-objective** method of Bordel et al.
+(2010, PLoS Comput Biol, doi:10.1371/journal.pcbi.1000859), as ported from RAVEN's
+``randomSampling``: each sample maximises a small random linear combination of
+reactions, so every sample is an *extreme point* (vertex) of the flux polytope.
+
+This is a different statistical object from cobrapy's ``cobra.sampling`` (OptGP /
+ACHR), which draw a (near-)uniform Markov-chain sample of the polytope *interior*.
+Use cobra's samplers when you need the uniform flux distribution; use this when you
+want a fast, robust spread of diverse optimal states — the workflow RAVEN uses to
+compare conditions, and one that stays well-behaved on large or tightly-constrained
+models where MCMC mixing is poor. cobrapy has no equivalent, so this is a genuine
+addition, not a wrapper.
+
+Improvements over RAVEN (see IMPROVEMENTS SAMP1):
+
+* **`good_reactions` via one FVA pass**, not a hand-rolled per-reaction ``parfor``
+  loop. A reaction is usable as a random objective if it can carry flux and is not
+  stuck in a stoichiometrically-infeasible loop (its range blows past the arbitrary
+  large bound). ``cobra``'s FVA computes exactly that, faster and in far less code,
+  and can optionally be made ``loopless``.
+* **Reproducible** via ``seed`` (RAVEN has no seed control).
+* **`n_objectives` is a parameter** (RAVEN hard-codes 2, though its docstring claims
+  3).
+* **Tidy output**: a ``samples`` DataFrame shaped samples × reactions (matching
+  ``cobra.sampling``), plus the reusable ``good_reactions`` list — instead of a
+  reactions × samples matrix and a parallel index vector.
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import cobra
+import numpy as np
+import pandas as pd
+from cobra.exceptions import OptimizationError
+from cobra.flux_analysis import flux_variability_analysis, pfba
+from optlang.symbolics import add
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RandomSamplingResult:
+    """Output of :func:`random_sampling`.
+
+    ``samples`` is a DataFrame of flux vectors shaped *n_samples × n_reactions*
+    (one sample per row, reaction ids as columns — the ``cobra.sampling`` layout).
+    ``good_reactions`` is the list of reaction ids that were eligible as random
+    objectives; pass it back in to skip the (one-off) FVA on a repeat run.
+    """
+
+    samples: pd.DataFrame
+    good_reactions: list[str]
+
+
+def find_good_reactions(
+    model: cobra.Model,
+    *,
+    flux_tol: float = 1e-9,
+    loopless: bool = True,
+    exclude_reactions: Iterable[str] | None = None,
+) -> list[str]:
+    """Reactions usable as random objectives: carry real (non-loop) flux.
+
+    A reaction is kept if its FVA range spans more than ``flux_tol``. With
+    ``loopless`` (default) the FVA is loopless (``cycleFreeFlux``), so reactions
+    that can carry flux *only* through a thermodynamically-infeasible cycle have a
+    ~0 loopless range and are dropped — the right test for "loopy", unlike a fixed
+    bound threshold which wrongly drops legitimate reactions that simply reach the
+    model's default (e.g. 1000) bound. Pass ``loopless=False`` for a faster, looser
+    pass that keeps any flux-carrying reaction (loops included).
+    """
+    fva = flux_variability_analysis(
+        model, fraction_of_optimum=0.0,
+        loopless="cycleFreeFlux" if loopless else None,
+    )
+    excluded = set(exclude_reactions or ())
+    return [
+        rxn_id
+        for rxn_id, lo, hi in zip(fva.index, fva["minimum"], fva["maximum"], strict=True)
+        if rxn_id not in excluded and max(abs(lo), abs(hi)) > flux_tol
+    ]
+
+
+def random_sampling(
+    model: cobra.Model,
+    n_samples: int = 1000,
+    *,
+    n_objectives: int = 2,
+    good_reactions: Iterable[str] | None = None,
+    replace_max_bound: bool = False,
+    min_flux: bool = False,
+    loopless_good_reactions: bool = True,
+    exclude_reactions: Iterable[str] | None = None,
+    max_attempts: int = 100,
+    suppress_errors: bool = False,
+    seed: int | None = None,
+) -> RandomSamplingResult:
+    """Random-objective sampling of ``model``'s flux space (Bordel et al. 2010).
+
+    Each sample maximises ``sum(w_i * v_i)`` over ``n_objectives`` reactions drawn at
+    random from ``good_reactions``, with weights ``w_i = U(0,1) * (±1)`` (a random
+    sign per reaction, as in RAVEN). The resulting flux vector is one sample.
+
+    Parameters
+    ----------
+    n_samples
+        Number of flux vectors to return.
+    n_objectives
+        Reactions combined into each random objective (RAVEN's fixed 2).
+    good_reactions
+        Reaction ids eligible as objectives. If ``None`` they are computed once with
+        :func:`find_good_reactions` and returned for reuse.
+    replace_max_bound
+        RAVEN's ``replaceBoundsWithInf``: replace the largest upper bound with
+        ``+inf`` (and the smallest negative lower bound with ``-inf``) before
+        sampling, so a reaction whose biological maximum exceeds the model's
+        arbitrary cap is not pinned at it. **Off by default** — unlike RAVEN. It
+        applies only to the sampling phase (``good_reactions`` is always found on
+        the finite bounds), and it can open unbounded directions through loops
+        that show up as large fluxes in non-objective reactions; pair it with
+        ``min_flux`` if you enable it.
+    min_flux
+        After maximising the random objective, re-solve parsimoniously
+        (:func:`cobra.flux_analysis.pfba`) to minimise total flux at that optimum —
+        squeezes residual loops out of each individual sample.
+    loopless_good_reactions, exclude_reactions
+        Forwarded to :func:`find_good_reactions` when it is invoked (loopless loop
+        detection is on by default).
+    max_attempts, suppress_errors
+        A sample is retried if the random objective is degenerate (zero flux). After
+        ``max_attempts`` failures this raises, unless ``suppress_errors`` (then the
+        degenerate solution is kept with a warning).
+    seed
+        Seed for reproducible objective draws.
+
+    Returns
+    -------
+    RandomSamplingResult
+    """
+    if n_samples <= 0:
+        raise ValueError("n_samples must be positive.")
+    rng = np.random.default_rng(seed)
+    model = model.copy()
+
+    if model.slim_optimize(error_value=None) is None:
+        raise ValueError(
+            "The model has no feasible solution, likely due to incompatible constraints."
+        )
+
+    # good_reactions must be found on the finite bounds (FVA cannot handle inf),
+    # before any bound replacement.
+    if good_reactions is None:
+        good_reactions = find_good_reactions(
+            model, loopless=loopless_good_reactions,
+            exclude_reactions=exclude_reactions,
+        )
+    good_reactions = list(good_reactions)
+
+    if replace_max_bound:
+        max_ub = max(r.upper_bound for r in model.reactions)
+        min_lb = min(r.lower_bound for r in model.reactions)
+        for r in model.reactions:
+            if r.upper_bound == max_ub:
+                r.upper_bound = float("inf")
+            if min_lb < 0 and r.lower_bound == min_lb:
+                r.lower_bound = float("-inf")
+
+    if len(good_reactions) < n_objectives:
+        raise ValueError(
+            f"Only {len(good_reactions)} usable reactions found, need at least "
+            f"n_objectives={n_objectives}. Check the model's constraints."
+        )
+
+    good_rxn_objs = [model.reactions.get_by_id(r) for r in good_reactions]
+    reaction_ids = [r.id for r in model.reactions]
+    samples = np.zeros((n_samples, len(reaction_ids)))
+
+    for i in range(n_samples):
+        for attempt in range(1, max_attempts + 1):
+            chosen = rng.choice(len(good_rxn_objs), size=n_objectives, replace=False)
+            signs = rng.choice((-1.0, 1.0), size=n_objectives)
+            weights = rng.random(n_objectives) * signs
+            terms = [w * good_rxn_objs[j].flux_expression
+                     for j, w in zip(chosen, weights, strict=True)]
+            # add() (not sum()) builds the symbolic objective in one pass; sum()
+            # re-canonicalises the optlang expression on every term (O(n^2)).
+            model.objective = model.problem.Objective(add(terms), direction="max")
+            sol = model.optimize()
+            if sol.status == "optimal" and abs(sol.objective_value) > 1e-8:
+                fluxes = (pfba(model) if min_flux else sol).fluxes.reindex(reaction_ids)
+                if fluxes.isna().any():  # solver returned an unexpected reaction set
+                    missing = fluxes.index[fluxes.isna()].tolist()
+                    raise OptimizationError(
+                        "solver returned fluxes missing reaction(s) "
+                        f"{missing[:5]}; cannot assemble a NaN-free sample matrix."
+                    )
+                samples[i, :] = fluxes.to_numpy()
+                break
+            if attempt == max_attempts:
+                if not suppress_errors:
+                    raise OptimizationError(
+                        "Could not find a non-zero, loop-free solution after "
+                        f"{max_attempts} attempts for sample {i}. Review the model's "
+                        "constraints, or set suppress_errors=True."
+                    )
+                logger.warning("Sample %d: kept a degenerate solution after %d attempts.",
+                               i, max_attempts)
+                samples[i, :] = sol.fluxes.reindex(reaction_ids).to_numpy()
+
+    return RandomSamplingResult(
+        samples=pd.DataFrame(samples, columns=reaction_ids),
+        good_reactions=good_reactions,
+    )

raven_toolbox/annotation/__init__.py

@@ -0,0 +1,24 @@
+"""Annotation helpers — SBO term assignment, ΔG CSV persistence.
+
+These are the pieces of yeast-GEM's ``missingFields`` module that are
+organism-agnostic enough to live upstream. Default parameter values
+match the RAVEN/yeast convention so the functions are immediately
+useful on the standard layout; consumers with different naming pass
+overrides.
+"""
+from raven_toolbox.annotation.delta_g import load_delta_g_csv, save_delta_g_csv
+from raven_toolbox.annotation.sbo import (
+    DEFAULT_BIOMASS_MET_NAMES,
+    DEFAULT_BIOMASS_RXN_NAME,
+    DEFAULT_NGAM_RXN_NAME,
+    add_sbo_terms,
+)
+
+__all__ = [
+    "DEFAULT_BIOMASS_MET_NAMES",
+    "DEFAULT_BIOMASS_RXN_NAME",
+    "DEFAULT_NGAM_RXN_NAME",
+    "add_sbo_terms",
+    "load_delta_g_csv",
+    "save_delta_g_csv",
+]

raven_toolbox/annotation/delta_g.py

@@ -0,0 +1,115 @@
+"""Persist scalar annotations (Gibbs free energy, etc.) as a side-car CSV.
+
+The committed SBML standard has no slot for thermodynamic ΔG values, so
+projects like yeast-GEM keep them in a paired CSV instead. This module
+provides the generic load / save round-trip — the file format is a two
+column table ``<id>, <value>`` — and exposes the per-call schema so
+existing projects can configure their conventions.
+
+The functions operate on cobra ``.notes`` (string round-tripped through
+SBML), keeping any other notes untouched.
+"""
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+from pathlib import Path
+
+import cobra
+import pandas as pd
+
+
+def load_delta_g_csv(
+    entities: Iterable,
+    path: str | Path,
+    *,
+    id_column: str = "Var1",
+    value_column: str = "Var2",
+    note_key: str = "deltaG",
+    verbose: bool = False,
+) -> int:
+    """Stamp ``note_key`` on each entity from a CSV of ``id → value``.
+
+    Parameters
+    ----------
+    entities
+        Cobra entities (``model.metabolites`` or ``model.reactions``).
+    path
+        Path to the CSV.
+    id_column, value_column
+        Column labels in the CSV. Defaults match the yeast-GEM
+        convention (``Var1`` / ``Var2`` from MATLAB's ``array2table``).
+    note_key
+        Key under which the value is stored on ``entity.notes``.
+        Default ``"deltaG"``.
+    verbose
+        Print a summary of unmatched entity ids.
+
+    Returns
+    -------
+    The number of entities that were stamped (i.e. matched the CSV).
+    """
+    df = pd.read_csv(path)
+    if id_column not in df.columns or value_column not in df.columns:
+        raise ValueError(
+            f"{path} columns {list(df.columns)} do not contain "
+            f"both {id_column!r} and {value_column!r}"
+        )
+    lookup = dict(zip(df[id_column], df[value_column], strict=True))
+
+    stamped = 0
+    missing: list[str] = []
+    for entity in entities:
+        value = lookup.get(entity.id)
+        if value is None or (isinstance(value, float) and math.isnan(value)):
+            missing.append(entity.id)
+            continue
+        entity.notes[note_key] = str(value)
+        stamped += 1
+
+    if verbose and missing:
+        print(
+            f"{len(missing)} entity ids were not in {path} "
+            f"(e.g. {missing[:3]}); left untouched."
+        )
+    return stamped
+
+
+def save_delta_g_csv(
+    entities: Iterable,
+    path: str | Path,
+    *,
+    id_column: str = "Var1",
+    value_column: str = "Var2",
+    note_key: str = "deltaG",
+) -> int:
+    """Dump ``entity.notes[note_key]`` for each entity to a CSV.
+
+    Entities without ``note_key`` set get ``NaN`` written, preserving
+    one-row-per-entity ordering (mirrors MATLAB's ``array2table([ids,
+    values])`` behaviour).
+
+    Returns
+    -------
+    The number of rows written (= number of entities).
+    """
+    rows: list[tuple[str, float]] = []
+    for entity in entities:
+        raw = entity.notes.get(note_key)
+        if raw is None:
+            value: float = math.nan
+        else:
+            try:
+                value = float(raw)
+            except ValueError:
+                value = math.nan
+        rows.append((entity.id, value))
+    pd.DataFrame(rows, columns=[id_column, value_column]).to_csv(path, index=False)
+    return len(rows)
+
+
+# Re-export the cobra Model type for type-checker friendliness; helps
+# IDEs surface the right hints to callers that hand us model.metabolites
+# / model.reactions directly.
+__all__ = ["load_delta_g_csv", "save_delta_g_csv"]
+_ = cobra  # silence "imported but unused" — used for typing context above