Phase 1: Python package skeleton on the GECKO 4 ecModel

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [master, devel]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Test
+        run: pytest -v --durations=10

.gitignore

@@ -44,4 +44,18 @@ scrap/
 # Cloned repositories
 code/GECKO
 code/ecModels
-code/yeast-GEM
+code/yeast-GEM
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+build/
+dist/
+*.egg-info/
+.venv/
+
+# Solver
+gurobi.env
+gurobi.log

README.md

@@ -1,10 +1,67 @@
 [![Zenodo DOI](https://zenodo.org/badge/288161152.svg)](https://zenodo.org/badge/latestdoi/288161152)
 
+# overflow
 
-## Instructions
-The `code` folder contains a number of scripts to reconstruct the models and replicate the analysis. Note that the user should have [RAVEN 2.4.0](https://github.com/SysBioChalmers/RAVEN/releases) or later installed.
+Proteome-constrained enzyme-constrained model analysis of overflow metabolism
+in *Saccharomyces cerevisiae*, across four carbon/nitrogen ratios and one
+high growth rate condition.
 
-- `prepareEnvironment.m`: run this script to prepare MATLAB for model reconstruction and analysis. This includes (1) cloning the correct GECKO version; (2) if required cloning yeast-GEM and reconstructing ecYeast-GEM 8.1.3 [also already distributed with this repository]; (3) load all measured flux and proteomics data; (4) set parameters for GECKO.
-- `generateProtModels.m`: generate the five condition specific proteome-constrained ec-models, and store these in the models subdirectory. In `results/modelGeneration` is written which enzyme abundances were flexibilized to allow growth at the measured dilution rate. The models are constrained for glucose uptake, growth rate is set to dilution rate and the objective function is set to minimization of the unmeasured protein pool usage. Results from this FBA is written to `results/modelSimulation`.
-- `ribosome.m`: add ribosomal subunits to the ec-models. In `results/modelGeneration` is plotted the average abundances of the ribosomal subunits, to identify the "core" ribosome to be included in the model. Also written in this subdirectory is which subunit abundances were flexibilized to allow growth at the measured dilution rate.
-- `analyzeUsage.m`: run same FBA as in `generateProtModels` and summarize the enzyme usages in `results/enzymeUsage`, where the capacity and absolute usages are stored separately, together with a summary for each subsystem.
+The analysis is built on the GECKO 4 `ecYeastGEM` and runs in Python through
+[geckopy](https://github.com/SysBioChalmers/geckopy) and
+[raven-toolbox](https://github.com/SysBioChalmers/RAVEN). The MATLAB
+implementation that produced the published results, which used GECKO 2, is
+kept in [`legacy_matlab/`](legacy_matlab/).
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+Python 3.11 or later. A linear programming solver is required; the analysis
+scripts are developed against Gurobi, and the test suite runs on the GLPK
+solver that ships with cobrapy.
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| `data/` | Measured proteomics, fermentation rates, ribosome subunits, annotation |
+| `models/` | The GECKO 4 ecModel and the conventional GEM it derives from, see [`models/PROVENANCE.md`](models/PROVENANCE.md) |
+| `src/overflow/` | The analysis package |
+| `tests/` | Test suite |
+| `results/` | Output tables and figures |
+| `legacy_matlab/` | The GECKO 2 MATLAB implementation and its results |
+
+## Experimental data
+
+`data/fermentationData.txt` holds, per condition, the total protein content,
+the dilution rate and the measured exchange rates. `data/abs_proteomics.txt`
+holds absolute protein abundances in mmol/gDW: three biological replicates
+per condition, four for hGR.
+
+```python
+from overflow import load_conditions
+
+conditions = load_conditions()
+conditions["CN4"].d_rate          # 0.1
+conditions["CN4"].byproduct_bounds()   # undetected byproducts are blocked
+```
+
+## Model
+
+```python
+from overflow import build_adapter, load_model
+
+model = load_model(build_adapter(conditions["CN4"]))
+```
+
+`build_adapter` reads `model_adapter.toml` and layers the condition's measured
+protein content and dilution rate on top.
+
+## Tests
+
+```bash
+pytest                  # everything
+pytest -m "not slow"    # skip the tests that load a genome-scale model
+```

legacy_matlab/README.md

@@ -0,0 +1,27 @@
+# MATLAB implementation
+
+The GECKO 2 MATLAB pipeline that produced the published results, together
+with the models and result tables it generated. It is kept for reference and
+is not maintained; `code/prepareEnvironment.m` pins GECKO v2.0.0 and expects
+RAVEN 2.4.0.
+
+| | |
+|---|---|
+| `code/` | The five analysis scripts plus the four patched GECKO functions in `code/customGECKO/` |
+| `models/` | GECKO 2 ecModels (`.mat`) and the yeast-GEM releases they were built from |
+| `results/` | Tables and figures produced by those scripts |
+
+The Python pipeline in `src/overflow/` reproduces this analysis on a GECKO 4
+model. Where a step could be checked against these committed outputs rather
+than reimplemented on trust, the test suite does so.
+
+## What does not carry over
+
+GECKO 2 ecModels have no `ec` structure: enzymes appear as `prot_<id>`
+metabolites written directly into reaction stoichiometry, with one
+`prot_<id>_exchange` reaction per measured enzyme and a `prot_pool` covering
+only the unmeasured remainder. geckopy works through `model.ec` and
+`usage_prot_<id>` reactions in which every enzyme draws from one shared pool.
+The models here therefore cannot be driven from the Python pipeline, and the
+four patched functions in `code/customGECKO/` have no direct counterpart —
+their behaviour is reimplemented against GECKO 4 primitives instead.

model_adapter.toml

@@ -0,0 +1,32 @@
+# geckopy adapter parameters for the overflow ecModels.
+#
+# Defaults describe the model as distributed; the per-condition values
+# (p_tot, gr_exp) are overridden at build time from data/fermentationData.txt.
+# sigma = 1 because the enzyme constraints come from measured abundances
+# rather than from an assumed average saturation.
+
+conv_gem = "models/yeast-GEM.yml"
+
+org_name = "saccharomyces cerevisiae"
+
+sigma = 1.0
+p_tot = 0.5
+f = 0.5
+gr_exp = 0.1
+
+c_source = "r_1714"
+bio_rxn = "r_4041"
+enzyme_comp = "cytoplasm"
+
+[kegg]
+id = "sce"
+gene_id = "kegg"
+
+[uniprot]
+type = "proteome"
+id = "UP000002311"
+gene_id_field = "gene_oln"
+reviewed = true
+
+[complex]
+taxonomic_id = 559292

models/PROVENANCE.md

@@ -0,0 +1,36 @@
+# Model provenance
+
+## ecYeastGEM.yml
+
+The full enzyme-constrained yeast model, in GECKO 4 / RAVEN 3 YAML format.
+
+| | |
+|---|---|
+| Source | [SysBioChalmers/GECKO](https://github.com/SysBioChalmers/GECKO), `tutorials/full_ecModel/models/ecYeastGEM.yml` |
+| Branch | `develop4` |
+| Commit | `cbc4ca3311df8ca44c28792f40008b9cbef692bd` |
+| Blob | `891ad7ba769cdc7d0fd4b605b0fd625c8cdd6867` |
+| Built with | GECKO 4.0.0b1, RAVEN 3.0.0b1 |
+
+1144 enzymes over 4834 enzyme-constrained reactions. kcat sources: 3280 BRENDA,
+1076 DLKcat, 251 standard, 217 custom, 6 sensitivity-tuned, 3 isozyme-derived,
+1 set explicitly. Subunit stoichiometries come from Complex Portal.
+
+The model ships with `r_4046` (non-growth associated maintenance) pinned at
+0.7 mmol ATP/gDW/h and `prot_pool_exchange` bounded at 125 mg/gDW, which is
+`p_tot * f * sigma * 1000` for the distributed defaults. Both are replaced
+per condition when building the proteome-constrained models.
+
+## yeast-GEM.yml
+
+The conventional GEM the ecModel was built from, from the same commit. Used
+as `conv_gem` by the geckopy adapter and as the starting model for random
+sampling.
+
+## Verifying
+
+```bash
+curl -sL https://raw.githubusercontent.com/SysBioChalmers/GECKO/cbc4ca3311df8ca44c28792f40008b9cbef692bd/tutorials/full_ecModel/models/ecYeastGEM.yml \
+  | git hash-object --stdin
+# 891ad7ba769cdc7d0fd4b605b0fd625c8cdd6867
+```