Add raven_python.curation — batch_curate / batch_curate_from_tsv

Generic batch curation engine extracted from yeast-GEM's MATLAB
curateMetsRxnsGenes (yeast-GEM phase 6). Adds or updates
metabolites, reactions and genes from pandas DataFrames; a
batch_curate_from_tsv convenience wrapper reads the equivalent TSVs.

Schema (matches yeast-GEM's data/modelCuration/template/ layout):

  mets_df          metNames, comps, formula, charge, inchi, metNotes
                   + any number of MIRIAM-namespace columns
  genes_df         genes, geneShortNames + MIRIAM columns
  rxns_df          rxnNames, grRules, lb, ub, rev, subSystems,
                   eccodes, rxnNotes, rxnReferences,
                   rxnConfidenceScores + MIRIAM columns
  rxns_coeffs_df   rxnNames, metNames, comps, coefficient
                   (one row per (reaction, metabolite) pair)

Match keys:
  metabolites — (name, compartment) tuple
  genes       — gene id
  reactions   — stoichiometric signature

Existing entities get their annotations overwritten (warning emitted);
new entities are added with fresh ids generated from the supplied
``met_id_prefix`` / ``rxn_id_prefix`` (defaults M_ / R_ per the BiGG
convention; yeast-GEM passes s_ / r_). Width of the existing
zero-padded suffix is preserved so s_0001 → s_0002, not s_2.

"Everything after the core columns is MIRIAM" — the header of any
extra column becomes the annotation namespace key. Matches MATLAB
behaviour exactly so yeast-GEM's existing TSVs work unchanged, and
projects with different MIRIAM column sets need no code change.

CurationResult dataclass records what was added vs updated so
callers can verify in tests / CI.

Tests: 13 new (add/update mets, add/update genes, add/update rxns
by stoichiometry, miriam auto-detect, id-width preservation,
combined mets+rxns in one call, missing-metabolite error,
batch_curate_from_tsv round trip).

Author: edkerk

src/raven_python/curation/__init__.py

@@ -0,0 +1,54 @@
+"""Batch curation of metabolites / reactions / genes from data tables.
+
+Port of yeast-GEM's MATLAB ``curateMetsRxnsGenes`` into a generic
+DataFrame-driven engine. Other GEM projects (Human-GEM, custom
+reconstructions, …) can use the same machinery with their own TSV
+layouts; the only required pieces are the data tables and (optionally)
+project-specific id prefixes for fresh metabolites and reactions.
+
+Public API:
+
+* :func:`batch_curate` — entrypoint taking pandas DataFrames.
+* :func:`batch_curate_from_tsv` — file-path convenience wrapper.
+* :class:`CurationResult` — record of what was added / updated.
+
+Schema (mirrors yeast-GEM's ``data/modelCuration/template/`` layout):
+
+- **mets_df**: ``metNames, comps, formula, charge, inchi, metNotes``
+  + any number of MIRIAM-annotation columns. Match key is
+  ``(name, comp)``.
+- **genes_df**: ``genes, geneShortNames`` + MIRIAM columns. Match key
+  is ``genes``.
+- **rxns_df**: ``rxnNames, grRules, lb, ub, rev, subSystems, eccodes,
+  rxnNotes, rxnReferences, rxnConfidenceScores`` + MIRIAM columns.
+  Match key is the reaction's *stoichiometry* — same metabolites and
+  coefficients ⇒ same reaction.
+- **rxns_coeffs_df**: ``rxnNames, metNames, comps, coefficient``. One
+  row per ``(reaction, metabolite)`` pair. The ``rxnNames`` column
+  links each coefficient back to a row in ``rxns_df``. An optional
+  ``index`` first column from the legacy yeast-GEM schema is silently
+  ignored.
+
+Everything after the core columns in any of the four tables is
+interpreted as a MIRIAM annotation: the column header becomes the
+namespace key (``met.annotation[<header>] = <cell>``).
+"""
+from raven_python.curation.batch import (
+    DEFAULT_CORE_GENE_COLUMNS,
+    DEFAULT_CORE_MET_COLUMNS,
+    DEFAULT_CORE_RXN_COEFFS_COLUMNS,
+    DEFAULT_CORE_RXN_COLUMNS,
+    CurationResult,
+    batch_curate,
+    batch_curate_from_tsv,
+)
+
+__all__ = [
+    "DEFAULT_CORE_GENE_COLUMNS",
+    "DEFAULT_CORE_MET_COLUMNS",
+    "DEFAULT_CORE_RXN_COEFFS_COLUMNS",
+    "DEFAULT_CORE_RXN_COLUMNS",
+    "CurationResult",
+    "batch_curate",
+    "batch_curate_from_tsv",
+]