Release 4.0.0b1

.github/workflows/test.yml

@@ -36,7 +36,7 @@ jobs:
           cache-dependency-path: pyproject.toml
 
       - name: Install
-        run: pip install -e ".[dev]"
+        run: pip install -e ".[dev,evotune]"
 
       - name: Run pytest
         run: pytest -q

README.md

@@ -1,16 +1,21 @@
-# geckopy - under active development
+# geckopy
 
 [![tests](https://github.com/SysBioChalmers/geckopy/actions/workflows/test.yml/badge.svg)](https://github.com/SysBioChalmers/geckopy/actions/workflows/test.yml)
 
 Enzyme-constrained genome-scale metabolic modelling in Python.
 
-> **Disambiguation — this is not "geckopy 3.0".** The current geckopy is a new,
-> from-scratch port of the MATLAB [GECKO Toolbox](https://github.com/SysBioChalmers/GECKO).
-> It is unrelated to, and shares no code with, the earlier and separate `geckopy`
-> Python package ([on PyPI as `geckopy`](https://pypi.org/project/geckopy/)) 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). The two
-> projects share only the name.
+> **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.
+
+> **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).
 
 ## What this is
 
@@ -24,36 +29,47 @@ adds those limits to the network.
 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,
-applies custom curations, and integrates proteomics measurements.
+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: alpha.** All the MATLAB GECKO 3.2.5 functions used in the
-> standard ecModel build are ported. The yeast-GEM tutorial runs
-> end-to-end. Not yet on PyPI; install from GitHub for now.
+> **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.
 
 ## Install
 
 geckopy depends on [raven-toolbox](https://github.com/SysBioChalmers/raven-toolbox)
-(the Python port of the RAVEN Toolbox), which is not yet on PyPI. Install both
-from GitHub:
+(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:
 
 ```bash
-pip install \
-    git+https://github.com/SysBioChalmers/raven-toolbox.git@develop \
-    git+https://github.com/SysBioChalmers/geckopy.git@develop
+pip install --pre geckopy
 ```
 
-Once raven-toolbox and geckopy are published to PyPI, this collapses to
-`pip install geckopy` (raven-toolbox will be pulled in transitively).
+`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 "geckopy[tutorial] @ git+https://github.com/SysBioChalmers/geckopy.git@develop"
+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 "geckopy[dev] @ git+https://github.com/SysBioChalmers/geckopy.git@develop"
+pip install --pre "geckopy[dev]"
 ```
 
 Requires Python 3.11 or newer.
@@ -101,6 +117,10 @@ proteomics integration, and Crabtree-effect simulation) is in
 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,
@@ -119,13 +139,9 @@ specification and how it differs from the legacy MATLAB / RAVEN format.
 
 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. Where the Python
-version intentionally differs (different direction conventions, fixed
-MATLAB bugs, etc.), the divergence is tagged with a `MATLAB-COMPAT:`
-comment in source. The cumulative list of MATLAB-side improvements
-the port surfaced lives in
-[`docs/future_improvements.md`](docs/future_improvements.md).
-
+`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.
 ## License
 
 MIT. See [`LICENSE`](LICENSE), or the `license` field of

docs/cmaes_vs_abc_smc.md

@@ -0,0 +1,57 @@
+# Why this package tunes kcats with CMA-ES, not ABC-SMC
+
+DLKcat's own Bayesian approach to kcat tuning implements ABC-SMC
+(Approximate Bayesian Computation, Sequential Monte Carlo) --
+[SysBioChalmers/DLKcat/BayesianApproach](https://github.com/SysBioChalmers/DLKcat/tree/master/BayesianApproach).
+geckopy's `kcat_tuning.evotune` module ported that
+approach faithfully and tested it side by side with a plain optimiser,
+CMA-ES, on the same objective, the same screened parameter set, and
+the same experimental data (ecYeastGEM, 41 conditions). CMA-ES won on
+every criterion that was checked, so it is what this package ships.
+
+## What ABC-SMC does, and why that's the wrong tool here
+
+ABC-SMC is a sampler: each generation it draws a batch of candidate
+kcat vectors from a proposal distribution, scores them, and keeps the
+best fraction to seed the next generation's proposals. That machinery
+-- a posterior approximation, a sample schedule, truncation selection
+-- earns its keep when the goal is a *distribution* over plausible
+parameter values, and the model is cheap enough to sample densely
+across the whole parameter space.
+
+Once a screen has reduced the problem to the kcats the data can
+actually inform (a few dozen to a few hundred, out of thousands), that
+premise stops holding. There's no longer a broad space to sample
+across, and each evaluation is expensive (an FBA solve per condition).
+At that point the problem is a direct search for the best-fitting
+vector -- exactly what an optimiser is for, and exactly what ABC-SMC
+is not.
+
+## What the comparison showed
+
+Same model, same 112-parameter screen, same objective, three seeds
+each:
+
+| | distance | spread across seeds |
+|---|---|---|
+| ABC-SMC | 0.9156 | +/- 0.0549 |
+| **CMA-ES** | **0.7974** | **+/- 0.0048** |
+
+CMA-ES fits better by 3.7 standard errors, with a spread more than ten
+times tighter. The gap isn't just fit quality -- it's whether an
+individual tuned kcat means anything. Both methods leave most kcats on
+flat directions the data can't pin down, but ABC-SMC's posterior
+sampling wanders across the whole flat region: across three ABC-SMC
+seeds, lanosterol synthase (the single highest-leverage kcat in the
+model) took values of 0.338, 20.3, and 0.0781 1/s -- a 260-fold spread,
+at distances differing by 0.009. A number that unstable cannot be
+reported as a finding.
+
+CMA-ES doesn't remove flat directions -- nothing can, they're a
+property of the data, not the search method -- but a direct optimiser
+converges to one point per flat direction instead of sampling across
+it, and `prior_penalty_weight` (a Tikhonov-style penalty on moving away
+from the prior, weighted by how much each source is trusted) picks out
+which point: see `docs/evotune_kcat_tuning.md` for how that combines
+with `screen_kcat_leverage`/`select_tunable_mask` into the method this
+package actually recommends.