edkerk · Nov 2, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 9, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -13,3 +13,6 @@
 *.txt   text eol=lf
 *.xml   text eol=lf
 *.md    text eol=lf
+
+# A fixture that must keep its byte-order mark and CRLF line endings.
+tests/data/kcatSourceFixture.tsv -text
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -9,10 +9,6 @@ name: release
 #    https://pypi.org/manage/project/geckopy/settings/publishing/ , pointing
 #    at this repo, workflow filename `release.yml`, and environment `pypi`.
 # 2. Create a `pypi` environment in this repo's Settings -> Environments.
-# Also note: geckopy's `raven-toolbox` dependency is currently a git direct
-# reference (see pyproject.toml), which PyPI rejects on upload -- the
-# pypi-publish job below will fail until that's switched to a released
-# version pin.
 
 on:
   release:

diff --git a/.gitignore b/.gitignore
@@ -16,6 +16,8 @@ htmlcov/
 # Tutorial build outputs (the source yeast-GEM.yml is tracked).
 tutorials/full_ecModel/models/ecYeastGEM*.yml
 tutorials/full_ecModel/output/
+# Downloaded on first run by the tutorial (download_phyl_dist).
+tutorials/full_ecModel/data/PhylDist.mat
 
 # BRENDA bulk download (user drops the tarball here; derived TSVs are tracked).
 src/geckopy/data/brenda/_cache/
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -1,148 +1,61 @@
-# geckopy
-
-[![tests](https://github.com/SysBioChalmers/geckopy/actions/workflows/test.yml/badge.svg)](https://github.com/SysBioChalmers/geckopy/actions/workflows/test.yml)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/CompMetEng/geckopy/develop/img/gecko-logo-white.png">
+  <img src="https://raw.githubusercontent.com/CompMetEng/geckopy/develop/img/gecko-logo.png" alt="GECKO" width="400px">
+</picture>
 
-Enzyme-constrained genome-scale metabolic modelling in Python.
+[![tests](https://github.com/CompMetEng/geckopy/actions/workflows/test.yml/badge.svg)](https://github.com/CompMetEng/geckopy/actions/workflows/test.yml)
+[![Release](https://img.shields.io/github/v/release/CompMetEng/geckopy?include_prereleases)](https://github.com/CompMetEng/geckopy/releases/)
+[![Documentation](https://readthedocs.org/projects/gecko-docs/badge/?version=latest)](https://gecko-docs.readthedocs.io/en/latest/)
+[![GitHub Discussions](https://img.shields.io/github/discussions-search?query=repo%3ACompMetEng%2Fgeckopy&label=GitHub%20Discussions)](https://github.com/CompMetEng/geckopy/discussions)
 
-> **Full documentation for both MATLAB GECKO and geckopy — the six-stage
-> protocol, installation, troubleshooting, and complete API reference —
-> lives at [gecko-docs.readthedocs.io](https://gecko-docs.readthedocs.io/).**
-> This README only covers install and a quick orientation; that site is
-> the place to actually learn or look things up.
+**[Documentation](https://gecko-docs.readthedocs.io/en/latest/)** · [Installation](https://gecko-docs.readthedocs.io/en/latest/installation/) · [Guide](https://gecko-docs.readthedocs.io/en/latest/guide/) · [API reference](https://gecko-docs.readthedocs.io/en/latest/api/) · [Migrate](https://gecko-docs.readthedocs.io/en/latest/migrate.html) · [Citations](https://gecko-docs.readthedocs.io/en/latest/references.html)
 
-> **Disambiguation.** This is a new, from-scratch port of the
-> [GECKO Toolbox](https://github.com/SysBioChalmers/GECKO) (MATLAB). It is unrelated to
-> the earlier and separate `geckopy` Python package
-> ([on PyPI as release 2.0.2 and earlier](https://pypi.org/project/geckopy/2.0.2/))
-> described in Carrasco Muriel, Long & Sonnenschein, *Microbiology Spectrum*
-> 11(6):e01705-23 (2023), [doi:10.1128/spectrum.01705-23](https://doi.org/10.1128/spectrum.01705-23).
+# geckopy
 
-## What this is
+Enzyme-constrained genome-scale metabolic modelling in Python: the Python port of the [GECKO Toolbox](https://github.com/CompMetEng/GECKO) (MATLAB). It builds on [cobrapy](https://github.com/opencobra/cobrapy) and [raven-toolbox](https://github.com/CompMetEng/raven-toolbox), and reads and writes the same ecModel YAML files as GECKO, so ecModels move between the two toolboxes without conversion.
 
-Genome-scale metabolic models (GEMs) describe an organism's chemistry as a
-big network of reactions. A standard GEM lets each reaction run as fast as
-its substrates allow. In reality, enzymes catalyse those reactions, and
-each enzyme has a finite capacity (its kcat) and a finite supply (the
-cell's total protein budget). An *ec*Model (enzyme-constrained model)
-adds those limits to the network.
+An *ec*Model adds the limits of enzymes to a genome-scale model: each enzyme has a finite capacity (its kcat) and the cell has a finite protein budget. geckopy fetches kcats from BRENDA, predicts them with DLKcat, tunes them against growth and flux data with CMA-ES, applies custom curations and integrates proteomics.
 
-geckopy is a Python port of the [GECKO Toolbox](https://github.com/SysBioChalmers/GECKO)
-(MATLAB). It builds on [cobrapy](https://github.com/opencobra/cobrapy) for
-the standard modelling layer, then layers GECKO's enzyme-constraint machinery
-on top: it fetches kcat values from BRENDA, predicts them with DLKcat, tunes
-them against experimental growth/flux data with CMA-ES, applies custom
-curations, and integrates proteomics measurements.
+> **Status: beta (`4.0.0b2`).** The yeast-GEM tutorial runs end to end. The major and minor version follow GECKO, which is why it starts at 4.
 
-> **Status: beta (`4.0.0b1`).** All the MATLAB GECKO 3.2.5 functions used in
-> the standard ecModel build are ported, and the yeast-GEM tutorial runs
-> end-to-end. geckopy's major and minor version number (x.y.-) will follow
-> the MATLAB GECKO numbering, justifying a jump to version 4.
+> **Not the older geckopy.** This is a new port of GECKO. It is unrelated to the earlier `geckopy` on PyPI (release 2.0.2 and earlier), described in Carrasco Muriel, Long & Sonnenschein, *Microbiology Spectrum* 11(6):e01705-23 (2023), [doi:10.1128/spectrum.01705-23](https://doi.org/10.1128/spectrum.01705-23).
 
 ## Install
 
-geckopy depends on [raven-toolbox](https://github.com/SysBioChalmers/raven-toolbox)
-(the Python port of the RAVEN Toolbox). Both are currently pre-releases on
-PyPI, so a plain `pip install geckopy` will install the wrong version — `--pre` is
-required:
+Both geckopy and raven-toolbox are pre-releases, so pip needs `--pre`:
 
 ```bash
 pip install --pre geckopy
 ```
 
-`raven-toolbox` doesn't need to be named separately: geckopy's own dependency
-on it already specifies `>=3.0.0b1`, and a specifier that names a pre-release
-opts pip into matching pre-releases for that package too, `--pre` or not. To
-pin the exact versions this was written against instead of "whatever's
-newest," name both explicitly:
-
-```bash
-pip install raven-toolbox==3.0.0b1 geckopy==4.0.0b1
-```
-
-Optional extras:
-
-```bash
-# Adds matplotlib (needed to render plots from the tutorial)
-pip install --pre "geckopy[tutorial]"
-
-# Adds cma (needed for CMA-ES kcat tuning, geckopy.kcat_tuning.evotune)
-pip install --pre "geckopy[evotune]"
-
-# Adds pytest + ruff (only needed if you're contributing)
-pip install --pre "geckopy[dev]"
-```
-
-Requires Python 3.11 or newer.
+Extras: `geckopy[tutorial]` (matplotlib), `geckopy[evotune]` (cma, for kcat tuning) and `geckopy[dev]` (pytest and ruff). Python 3.11 or newer.
 
 ## Quick start
 
-A minimal end-to-end build, assuming you have a project folder set up the
-way the tutorial expects (`model_adapter.toml` + `models/` + `data/`):
+A minimal build, for a project folder with `model_adapter.toml`, `models/` and `data/`:
 
 ```python
-from geckopy import (
-    ModelAdapter,
-    load_conventional_gem,
-    load_uniprot_tsv,
-    make_ec_model,
-    save_ec_model,
-)
-
-# 1. The adapter holds organism-specific parameters (taxonomy id,
-#    biomass reaction, average enzyme saturation, etc.). They live in
-#    model_adapter.toml so they're easy to swap per organism.
-adapter = ModelAdapter.from_folder("my_project")
+from geckopy import ModelAdapter, load_conventional_gem, load_uniprot_tsv, make_ec_model, save_ec_model
 
-# 2. Load the starting GEM (the regular metabolic model you want to
-#    extend) and a cached UniProt query (for enzyme MW and sequence).
+adapter = ModelAdapter.from_folder("my_project")
 model = load_conventional_gem(adapter)
 uniprot = load_uniprot_tsv(adapter.params.path / "data" / "uniprot.tsv")
-
-# 3. Build the ecModel. This adds protein pseudo-metabolites, a shared
-#    protein pool, and per-enzyme usage reactions on top of the GEM.
 ec_model = make_ec_model(model, adapter, uniprot_db=uniprot)
-
-# 4. Save in geckopy's YAML format.
 save_ec_model(ec_model, "ecModel.yml", adapter=adapter)
 ```
 
-Every public function (loaders, kcat fetchers, FBA/FVA helpers,
-YAML I/O, ...) is reachable as `from geckopy import X` -- the
-subpackages exist for code organisation but you don't have to use
-them. See `geckopy.__all__` for the full list (~80 names).
-
-The full protocol (which adds kcat curation from BRENDA and DLKcat,
-proteomics integration, and Crabtree-effect simulation) is in
-[`tutorials/full_ecModel/protocol.py`](tutorials/full_ecModel/protocol.py).
-That script reproduces the MATLAB GECKO Nature Protocols tutorial in
-Python, step by step, and is the easiest way to see geckopy in action.
-
-Fitting kcats against measured growth rates and exchange fluxes (rather
-than looking them up) is a separate workflow, `geckopy.kcat_tuning.evotune`
-— see [`docs/evotune_kcat_tuning.md`](docs/evotune_kcat_tuning.md).
-
-## On-disk format
-
-geckopy reads and writes ecModels as **YAML**: a canonical,
-human-readable format that is a strict superset of cobrapy's YAML
-schema, with three extra top-level keys for the ec data (`ec-rxns`,
-`ec-enzymes`, `gecko_light`). Standard cobrapy tools (escher, memote,
-...) can read the cobra portion and silently ignore the GECKO
-extensions. The same format is read and written by MATLAB GECKO /
-RAVEN, so ecModels exchange between the two toolboxes with no
-translator. The schema and the parsing live in raven-toolbox.
-
-See [`docs/yaml_format.md`](docs/yaml_format.md) for the YAML
-specification and how it differs from the legacy MATLAB / RAVEN format.
-
-## Relationship to MATLAB GECKO
-
-geckopy is a function-by-function port: algorithmic fidelity comes
-first, Pythonic idiom second. Each ported source file carries a
-`Ported from GECKO MATLAB: <path>` docstring header. For current
-MATLAB ↔ Python behavioural differences, see [gecko-docs.readthedocs.io](https://gecko-docs.readthedocs.io/), the
-shared documentation site for both toolboxes.
+The guide covers each step: [Getting started](https://gecko-docs.readthedocs.io/en/latest/guide/getting-started.html), [Building an ecModel](https://gecko-docs.readthedocs.io/en/latest/guide/building-ec-model.html) and [Gathering kcats](https://gecko-docs.readthedocs.io/en/latest/guide/gathering-kcats.html). Every public function is available as `from geckopy import X`; `geckopy.__all__` lists them, and the [API reference](https://gecko-docs.readthedocs.io/en/latest/api/) documents them. The full protocol, with kcat curation, proteomics and Crabtree-effect simulation, is [`tutorials/full_ecModel/protocol.py`](tutorials/full_ecModel/protocol.py). Fitting kcats to measured growth and fluxes is described in [`docs/evotune_kcat_tuning.md`](docs/evotune_kcat_tuning.md).
+
+## Documentation and parity with GECKO
+
+The protocol, installation, troubleshooting and API reference for both toolboxes are at [gecko-docs](https://gecko-docs.readthedocs.io/). The ecModel YAML format is described in the [guide](https://gecko-docs.readthedocs.io/en/latest/guide/yaml-format.html) and in [`docs/yaml_format.md`](docs/yaml_format.md). geckopy ports GECKO function by function, and each source file names its MATLAB original. The [parity ledger](https://github.com/CompMetEng/raven-gecko-parity) records, for every public function, whether the two agree and why where they do not.
+
+## Cite us
+
+If you have used geckopy in your work, please cite the GECKO protocol:
+
+> Chen Y, Gustafsson J, Tafur Rangel A, Anton M, Domenzain I, Kittikunapong C, Li F, Yuan L, Nielsen J & Kerkhoven EJ. Reconstruction, simulation and analysis of enzyme-constrained metabolic models using GECKO Toolbox 3.0. *Nature Protocols* **19**, 629-667 (2024). doi:[10.1038/s41596-023-00931-7](https://doi.org/10.1038/s41596-023-00931-7).
+
 ## License
 
-MIT. See [`LICENSE`](LICENSE), or the `license` field of
-[`pyproject.toml`](pyproject.toml).
+MIT. See [`LICENSE`](LICENSE).
diff --git a/docs/evotune_kcat_tuning.md b/docs/evotune_kcat_tuning.md
@@ -319,10 +319,16 @@ leverage_by_rxn = dict(zip(screen["rxn_id"], screen["leverage"]))
 leverage = [leverage_by_rxn.get(r, 0.0) for r in result.rxns]
 
 annotations = annotate_from_model(model, result.rxns)
-rows = result.corrections(leverage=leverage, **annotations)
+rows = result.corrections(
+    leverage=leverage,
+    names=annotations["names"], ec_codes=annotations["ec_codes"],
+)
 open("corrections.tsv", "w").write(corrections_tsv(rows))
 ```
 
+`annotate_from_model` also returns `sources`, which `corrections()`
+takes from `result.groups` itself rather than as a keyword.
+
 `cumulative_share` on each row is the running fraction of total leverage
 the list has accounted for so far, so a reader can stop where it stops
 climbing rather than reading every row. This is the tuning-time

diff --git a/docs/future_improvements.md b/docs/future_improvements.md
@@ -10,7 +10,7 @@ weren't blocking. Three audiences:
   spotted while comparing the two implementations side by side. For
   the current, maintained list of MATLAB ↔ Python behavioural
   differences (broader than just what's tracked here), see the
-  [MATLAB ↔ Python translation guide](https://gecko-docs.readthedocs.io/en/latest/api/translation/)
+  [GECKO vs. geckopy](https://gecko-docs.readthedocs.io/en/latest/gecko-to-geckopy.html) page
   on [gecko-docs.readthedocs.io](https://gecko-docs.readthedocs.io/).
 - **anyone hitting a strange dependency bug** — section
   "Third-party library gotchas".
@@ -134,7 +134,9 @@ Notable items:
   the docstring's origin ranking implies origin 4 should win. Either
   swap the search order so any-no-subs-kcat is tried before org-SA,
   or update the docstring to match the search order. geckopy
-  replicates the current MATLAB behavior; see the note in
+  replicates the current MATLAB behavior, both within one EC number
+  and when selecting among the EC numbers of one reaction; see
+  `SEARCH_LEVELS` and `SEARCH_RANK` in
   `fuzzy_kcat_matching/_brenda_query.py`.
 - Delete `updateProtPool` from MATLAB GECKO. The function has been
   obsolete since GECKO 3.2.0 (all enzymes, measured and unmeasured,

diff --git a/docs/gecko_light_status.md b/docs/gecko_light_status.md
@@ -38,7 +38,7 @@ smaller models (yeast, *E. coli*), full is usually fine.
 
 ```python
 ec_model = make_ec_model(model, adapter, gecko_light=True)
-set_kcat_for_reactions(ec_model, ["R2"], 5.0)   # broadcasts to all isozyme rows
+set_kcat_for_reactions(ec_model, ["001_R2", "002_R2"], 5.0)   # one row per isozyme
 apply_kcat_constraints(ec_model)                 # picks cheapest isozyme per cobra rxn
 set_prot_pool_size(ec_model)
 ec_model.optimize()
@@ -67,7 +67,7 @@ isn't checked out next to geckopy.
 | `src/geckopy/ec_model/make_ec_model.py` | dispatches stage 5 (isozyme split) and stages 9/11 (per-enzyme prot mets + usage rxns) off; calls `allocate_ec_and_coupling_light` instead of the full stages 6/8 |
 | `src/geckopy/ec_model/pipeline/populate_ec.py` | `allocate_ec_and_coupling_light` builds `ec.rxns` (one row per isozyme with the `###_` prefix) and `ec.rxn_enz_mat` in one pass; `split_light_rxn_id` is the inverse |
 | `src/geckopy/ec_model/pipeline/apply_kcat.py` | `_apply_kcat_constraints_light` groups ec rows by cobra reaction, picks the lowest-cost isozyme, writes `-MW_sum / (kcat * 3600)` as the `prot_pool` coefficient; same clear-then-write idempotency contract as full |
-| `src/geckopy/ec_model/pipeline/set_kcat.py` | recognises the `###_` prefix as the light analogue of `_EXP_<N>`; bare base names broadcast to every isozyme row |
+| `src/geckopy/ec_model/pipeline/set_kcat.py` | the `###_` prefix is part of the id in a light model: `001_R2` matches that one row and a bare cobra id such as `R2` matches nothing |
 | `src/geckopy/ec_model/enzyme.py` | `Enzyme.reactions` strips the prefix and dedupes; `Enzyme.mw` setter passes ec.rxns ids (not cobra ids) to `apply_kcat_constraints`; `_repr_html_` catches the light NotImplementedError |
 | `src/geckopy/gather_kcats/fuzzy_kcat_matching.py` | strips the `###_` prefix for cobra lookups |
 | `src/geckopy/gather_kcats/get_standard_kcat.py` | `_ec_rxn_to_cobra_id` handles both forms |

diff --git a/docs/internal/raven_inventory.md b/docs/internal/raven_inventory.md
@@ -1,7 +1,7 @@
 # RAVEN function inventory
 
 GECKO MATLAB is built on top of
-[RAVEN](https://github.com/SysBioChalmers/RAVEN), a MATLAB toolkit
+[RAVEN](https://github.com/CompMetEng/RAVEN), a MATLAB toolkit
 for genome-scale metabolic modelling. RAVEN handles all the
 low-level work: parsing SBML files, editing reactions and
 metabolites, solving FBAs, manipulating gene-protein-reaction

diff --git a/docs/kcat_aggregation.md b/docs/kcat_aggregation.md
@@ -1,6 +1,6 @@
 # kcat aggregation: how far is `max` from `median` on BRENDA?
 
-The bundled BRENDA snapshot ships **both** the per-(ec, substrate,
+The BRENDA files (toolbox-assets release `brenda-2026.1-1`) carry **both** the per-(ec, substrate,
 organism) max and the per-triple median of all raw measurements that
 fell into the triple. They live in the same `kcat.tsv` / `sa.tsv` file
 distinguished by an `aggregation` column; `load_brenda_data` splits
@@ -20,7 +20,7 @@ diffusion-limited filter in `parse_brenda_json`):
 - [`scripts/kcat_aggregation_raw.py`](../scripts/kcat_aggregation_raw.py)
   walks the raw JSON and answers both questions below.
 - [`scripts/kcat_aggregation_compare.py`](../scripts/kcat_aggregation_compare.py)
-  reads only the bundled TSV (no 710 MB JSON needed) and compares
+  reads only the BRENDA TSV (no 710 MB JSON needed) and compares
   per-EC max-of-max vs median-of-median over the pre-aggregated views.
 
 > **3.4.21.4 (trypsin) is excluded** from these analyses: its BRENDA
@@ -158,5 +158,5 @@ python scripts/kcat_aggregation_raw.py       # raw-JSON, both layers
 python scripts/kcat_aggregation_compare.py   # snapshot-only, per-EC
 ```
 
-Raw-JSON takes ~6 min on the bundled snapshot (limited by 710 MB JSON
+Raw-JSON takes ~6 min on the BRENDA 2026.1 dump (limited by 710 MB JSON
 load via WSL2 /mnt/c); snapshot-only runs in ~10 s.