Add shared yeast-GEM helpers: parseYAML, applyCondition, biomass, SBO, deltaG, findDuplicateRxns, curateModelFromTables

[edkerk]

Generic helpers extracted from yeast-GEM's MATLAB code as part of its Python port. All organism-agnostic; yeast-GEM consumes them via thin shims with its own data files / id prefixes.

What lands

I/O & condition handling

• io/parseYAML.m — generic YAML reader for arbitrary documents. Complements the existing model-format-only readYAMLmodel. Delegates to py.yaml.safe_load via MATLAB's Python bridge; py-side returns are recursively converted to native MATLAB struct / cell. Used by yeast-GEM to read its data/conditions/*.yml and data/yeastgem/ids.yml.

• core/applyCondition.m — apply a deterministic "condition" to a model from a YAML file or pre-parsed struct. Schema: prelude (reset_exchanges), cofactor_pseudoreaction (metabolite removals + automatic charge rebalance of an H+ met), biomass_stoichiometry_delta (combine with existing coefficients), per-reaction bounds diff, expected_uptake_count sanity check. Project-specific extensions (yeast-GEM's amino_acid_ratio step) are handled by the caller — upstream contract stays narrow.

• core/curateModelFromTables.m — generic batch-curation engine extracted from yeast-GEM's curateMetsRxnsGenes. Adds or updates metabolites / reactions / genes from TSV inputs. New parameters metPrefix and rxnPrefix (default 'M_' / 'R_') let any GEM project use the engine with its own id conventions; yeast-GEM keeps a thin curateMetsRxnsGenes shim that pins 's_' / 'r_' and forwards here. Schema otherwise identical to the legacy yeast-GEM version, so existing yeast-GEM TSVs work unchanged.

Biomass helpers

• core/getBiomassFractions.m — compute mass fraction (g/gDW) per biomass component plus the total, parameterised by a biomassConfig struct. Supports four mass_strategy modes: mw, mw_minus_2h (charged tRNAs), mw_minus_water (RNA / DNA polymerisation), grams (stoichiometry already in g/gDW). yeast-GEM's sumBioMass becomes a thin shim.

• core/scaleBiomassFraction.m — rescale a component to a target g/gDW, optionally adjusting a second component so the total stays at 1 g/gDW. Replaces the body of yeast-GEM's scaleBioMass.

• core/scaleBiomassPseudoreaction.m — multiply the substrate coefficients of one component pseudoreaction by a factor and rebalance H+ via biomassConfig.proton_met to preserve charge neutrality. Replaces the body of yeast-GEM's rescalePseudoReaction.

• core/setGAM.m — set the GAM coefficient on the biomass pseudoreaction for a configurable list of cofactor metabolite names; optionally fix an NGAM reaction's bounds. Replaces the body of yeast-GEM's changeGAM.

Annotation helpers

• core/assignSBOterms.m — generic SBO term assignment ported from yeast-GEM's addSBOterms. Parameterised entirely by an opts struct (biomass met names / suffixes, biomass / NGAM reaction names, pseudoreaction substrings). Writes via editMiriam(..., 'fill') so pre-existing SBO annotations are preserved. Includes opts.onlyLastReactionForPseudo as a bug-compat flag — the legacy yeast-GEM loop used for i = numel(model.rxns) instead of 1:numel(...), tagging only the last reaction; default off, yeast-GEM's shim turns it on so its saveYeastModel output stays byte-stable.

• io/loadDeltaGfromCSV.m / io/saveDeltaGtoCSV.m — generic load / save of metDeltaG and rxnDeltaG fields against two-column CSVs (id, deltaG). yeast-GEM's loadDeltaG / saveDeltaG become thin wrappers that supply the project paths.

YAML I/O alignment

• io/writeYAMLmodel.m + io/readYAMLmodel.m — three-way alignment between RAVEN MATLAB, raven-python, and cobrapy YAML output. Cobrapy is treated as canonical for the core (id / name / metabolites / reactions / genes / compartments / annotation / bounds); RAVEN-only fields (inchis, deltaG, metFrom, eccodes, rxnFrom, references, confidence_score, protein, metaData, ec-rxns / ec-enzymes) are additive extensions kept in their familiar positions. Writer changes:

  • Field order now matches cobrapy (charge before formula; notes before annotation; objective_coefficient after gene_reaction_rule; subsystem before annotation).
  • preserveQuotes default flipped to false to match cobrapy's minimal-quoting style; values that need quoting (SMILES strings with [O-], booleans, leading flow indicators, embedded : ) are still quoted defensively via a new needsYamlQuoting helper.
  • Reaction notes are now written as notes (cobrapy-canonical), not rxnNotes. Reader accepts both for backward compat.
  • Metabolite smiles moves into annotation.smiles (cobrapy convention). Reader still accepts top-level smiles.
  • gecko_light is emitted at the top level (matches raven-python) instead of inside metaData.
  • Whole-number bounds emit as 1000.0 not 1000 (matches cobrapy / Python float repr).
  • Empty metabolites: blocks emit !!omap [] so the file is a valid YAML 1.2 document.
  • Document-start marker (---) dropped to match cobrapy's bare !!omap root.

  Reader changes: accepts cobrapy's root-level id / name / version / gecko_light; accepts the !!omap-tagged metaData header; accepts both notes and rxnNotes reaction keys; defensive against subSystems shapes produced by the reader's own post-processing flatten.

  Verified: cobra.io.load_yaml_model and raven_python.read_yaml_model both successfully read every file the new writer produces (cobra mini.yml and the 2748-met yeast-GEM.yml). Round-tripping yeast-GEM through writeYAMLmodel preserves 2748/2748 metabolites, 4102/4102 reactions, 1143/1143 genes, 2411 eccodes, 3984 reaction deltaG, 2696 metabolite deltaG, 1788 SMILES, 1443 reaction notes — no semantic drift.

Misc

• core/findDuplicateRxns.m — return reaction pairs sharing identical stoichiometry, treating A->B and B->A as duplicates by default. Counterpart of raven_python.manipulation.find_duplicate_reactions and the upstream version of yeast-GEM's findDuplicatedRxns (which becomes a thin printing wrapper).

Lock-step verification

A MATLAB equivalence harness loaded yeast-GEM and ran every legacy implementation (extracted from git show HEAD:...) against its refactored shim on the same model state, asserting bitwise match on the S matrix, bounds, and miriam annotations (or near-zero float diff for deltaG / sumBioMass scalars). 10 / 10 checks pass — sumBioMass, rescalePseudoReaction (all 9 components incl. lipid aggregation), scaleBioMass (with balance_out), changeGAM (with and without NGAM), addSBOterms (mets and rxns), loadDeltaG, saveDeltaGtoCSV round-trip, and findDuplicateRxns. Details in each commit message and in yeast-GEM's PORTING_PLAN.md.

Companion PRs

• raven-python (Python counterparts): Add yeast-GEM-derived shared modules (diff, annotation, conditions, biomass, curation) raven-python#17
• yeast-GEM (consumer / thin shims): Python port of yeast-GEM (phases 1–7, built on raven-python) yeast-GEM#385