README: shorter, with the GECKO logo and the protocol citation

README.md

@@ -1,148 +1,61 @@
-# geckopy
+<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>
 
 [![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)
 
-Enzyme-constrained genome-scale metabolic modelling in Python.
-
-> **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/CompMetEng/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
-
-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.
-
-geckopy is a Python port of the [GECKO Toolbox](https://github.com/CompMetEng/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.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
+**[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)
 
-geckopy depends on [raven-toolbox](https://github.com/CompMetEng/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:
+# geckopy
 
-```bash
-pip install --pre geckopy
-```
+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.
 
-`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:
+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.
 
-```bash
-pip install raven-toolbox==3.0.0b1 geckopy==4.0.0b1
-```
+> **Status: beta (`4.0.0b1`).** The yeast-GEM tutorial runs end to end. The major and minor version follow GECKO, which is why it starts at 4.
 
-Optional extras:
+> **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).
 
-```bash
-# Adds matplotlib (needed to render plots from the tutorial)
-pip install --pre "geckopy[tutorial]"
+## Install
 
-# Adds cma (needed for CMA-ES kcat tuning, geckopy.kcat_tuning.evotune)
-pip install --pre "geckopy[evotune]"
+Both geckopy and raven-toolbox are pre-releases, so pip needs `--pre`:
 
-# Adds pytest + ruff (only needed if you're contributing)
-pip install --pre "geckopy[dev]"
+```bash
+pip install --pre geckopy
 ```
 
-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).