Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
2a457c7
doc: drop API pairs of deprecated functions and rename the tuning cat…
edkerk Nov 11, 2026
d878a58
doc: rewrite the guide for GECKO 4 as a quick path and decision pages
edkerk Nov 11, 2026
299c84a
doc: correct the migration pages for sigmaFitter, DLKcat and deprecat…
edkerk Nov 11, 2026
b3264e6
doc: correct the guide after review and split the analysis page
edkerk Nov 11, 2026
23d4ba6
doc: describe the guide structure and record its decisions
edkerk Nov 11, 2026
dc9b909
doc: apply docs-prose and add Setup and Troubleshooting sections
edkerk Nov 11, 2026
ec2a7eb
doc: describe the GECKO 4 code changes in the guide and the migration…
edkerk Nov 11, 2026
f16aad8
doc: correct third-round review findings
edkerk Nov 11, 2026
b31d0ac
doc: state that the UniProt and KEGG identifiers have no default
edkerk Nov 11, 2026
2a8718f
doc: describe the new full tutorial and the empty organism ids
edkerk Nov 11, 2026
7c5c13b
doc: drop the geckopy dlkcat aliases from the migration page
edkerk Nov 12, 2026
4f71e0c
Merge branch 'develop' into doc/gecko4-guide
edkerk Nov 12, 2026
0ad6140
doc: say that deprecated adapter classes warn when they are loaded
edkerk Nov 12, 2026
f9a78e5
doc: list only gecko 3 functions as removed or renamed and correct th…
edkerk Nov 12, 2026
0369348
doc: restore the workflow diagrams, ordered by the guide pages
edkerk Nov 13, 2026
2362225
doc: show the place of each guide page in the workflow
edkerk Nov 13, 2026
b9164f0
doc: correct the order and conditions in the workflow diagrams
edkerk Nov 13, 2026
1808aa6
doc: mark the optional steps of the proteomics and tuning diagrams
edkerk Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ One documentation site for **GECKO**, the MATLAB toolbox, and **geckopy**, its P

- **Home** (`docs/index.md`): one sentence on GECKO and geckopy, the install tabs for both languages, key features, quick start, links to the papers.
- **Installation** (`docs/installation/`).
- **Guide** (`docs/guide/`): *Start* (Introduction, Installation), *Guide* (ten task pages from getting started to enzyme usage and bottlenecks), *Background* (GECKO light, the YAML format, the files of the data folder, the model adapter parameters). The Introduction and the Background pages explain a concept or a format and are marked `<!-- docs-site: concept-page -->`, so they need no function table.
- **Guide** (`docs/guide/`): *Start* (Introduction, Installation), *Quick path* (Build an ecModel: a working ecModel with the default settings), *Decisions* (one page per choice the user makes, in the order the user meets it: the ecModel structure, the kcat sources, custom kcats, the protein pool, the kcat tuning, the advanced kcat tuning, proteomics, relaxing proteomics, analysis, engineering targets, context-specific ecModels, enzyme usage and bottlenecks), *Background* (the YAML format, the files of the data folder, the model adapter parameters, basic model operations). A decision page sets out the options (what each needs and changes), gives a recommendation where a source supports one, and then the procedure of each option. The guide describes GECKO 4 only; the migration pages describe the changes against GECKO 3. The Introduction and the YAML, data folder and model adapter pages explain a concept or a format and are marked `<!-- docs-site: concept-page -->`, so they need no function table.
- **Migration**: `migrate.md`, `gecko3-to-gecko4.md` and `gecko-to-geckopy.md`.
- **API reference** (`docs/api/`): a hand-written index, then generated MATLAB pages by folder and Python pages by package, and `docs/matlab-vs-python.md`.
- **References** (`docs/references.md`): the papers to cite.
Expand All @@ -58,7 +58,8 @@ One documentation site for **GECKO**, the MATLAB toolbox, and **geckopy**, its P

- **Unresolved names.** `scripts/check_names.py` reports 121 distinct names on the guide pages that are neither a top-level function or class of the toolboxes nor in `scripts/known_names.txt`. Most are keyword arguments, struct fields, YAML keys and variables of the examples; four (`cap_usage`, `from_folder`, `shadow_price`, `upper_bound`) are methods or properties. Someone who knows the pages has to sort them, and allow-list the ones that are not functions, before the check can block CI.
- **Link check.** `docs-build.yml` does not fail on the link check yet; the state of the external links was not known when the check was added.
- **Guide page sections.** Most guide pages have no "What can go wrong" section and no function table; `scripts/check_site.py` reports this as a warning.
- **Site scripts.** `scripts/check_site.py` and `scripts/autolink.py` differ from `docs-site/scripts` on main (the expected section names), and `check_style.py` and `run_examples.py` are missing. Until they are copied, `check_site.py` reports the section names "Functions on this page" and "What can go wrong" as missing on pages that use "Functions" and "Troubleshooting".
- **Examples are not run.** The code blocks of the guide are written from the source and have not been executed; the site has no `run_examples.py` and no examples workflow yet.

## 8. Decisions log

Expand All @@ -68,3 +69,8 @@ One documentation site for **GECKO**, the MATLAB toolbox, and **geckopy**, its P
- 2026-10-24: the language of the code tabs (MATLAB or Python) is remembered in `localStorage` by `docs/_static/language-sync.js`, so it applies to every tab on a page, to the next pages, to new browser tabs and to later visits, and install tabs follow it. sphinx-design alone keeps the choice in `sessionStorage` for one browser tab.
- **Broken links and code owner:** `.github/workflows/link-issue.yml` checks the external links every Wednesday and keeps one open issue labelled `broken-links` with the broken ones; it closes the issue when none is broken. `.github/CODEOWNERS` names `@edkerk` as the owner of the repository, who is asked to review every pull request.
- **Rules for every session:** `CLAUDE.md` holds the baseline rules of the `craft` plugin, `.claude/settings.json` enables the `craft` and `docs-site` plugins and turns on the hooks in `.githooks`, and `.github/workflows/repo-hygiene.yml` runs `.github/scripts/repo_hygiene.py` on every pull request. They refuse a tool author, trailer, mention, branch name or pull request footer.
- 2026-11-11: the guide no longer follows the order of the GECKO 3 Nature Protocols pipeline. GECKO 4 is configured by `model_adapter.toml`, and `assignKcats` replaces the manual steps of gathering, merging and applying kcats, so most of the work is choosing settings. The guide has one quick-path page and one page per decision; each page was written from the code, not edited from the earlier pages.
- 2026-11-11: the workflow diagrams (`docs/_static/workflow-*.pdf`, `workflow-overview.png`, the Mermaid page `guide/workflow.md`) and the table of approximate timings are removed. The diagrams showed the order of the GECKO 3 protocol, and the timings had no source.
- 2026-11-11: the guide calls `sensitivityTuning` the standard kcat tuning (it needs one maximum growth rate) and `cmaesKcatTuning` the advanced kcat tuning (it fits maximum growth rates and exchange fluxes of one or more conditions). They are alternatives; neither is called legacy. The API category of `src/kcat_tuning` is named kcat tuning.
- 2026-11-11: DLKcat predictions are described as coming from the DLKcat method of OpenKineticsPredictor, which `kcatsFromDLKcat` uses when `data/DLKcat.tsv` does not exist; the local Docker run is described as the older method in one admonition.
- 2026-11-11: the guide describes KinForm-H as the default OpenKineticsPredictor method and the presets' `okp` stage with KinForm-H alone, as GECKO and geckopy set it. Where the guide cites the measured comparison of the presets, it states that the comparison combined eight OKP methods. Functions that GECKO deprecates (`updateProtPool`, `mergeDLKcatAndFuzzyKcats`, adapter classes) appear on guide pages only in troubleshooting, and on the migration page.
Binary file modified docs/_static/workflow-matlab.pdf
Binary file not shown.
Binary file modified docs/_static/workflow-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/_static/workflow-python.pdf
Binary file not shown.
6 changes: 2 additions & 4 deletions docs/gecko-to-geckopy.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,6 @@ The table is a selection; [MATLAB and Python](matlab-vs-python.md) lists all pai
| `reviewKcatAssignment` | `review_assignment` |
| `upgradeGECKOproject` | `upgrade_project`, command `geckopy upgrade` |
| `createGECKOproject` | command `geckopy init` |
| `writeOpenKineticsPredictorInput` | `build_okp_input_csv` in `geckopy.gather_kcats.open_kinetics_predictor` |
| `readOpenKineticsPredictorOutput` | `parse_okp_output` in `geckopy.gather_kcats.open_kinetics_predictor` |

## Functions of one implementation

Expand All @@ -71,15 +69,15 @@ The table is a selection; [MATLAB and Python](matlab-vs-python.md) lists all pai
|---|---|
| Result and data types | `TunedKcatsResult`, `FlexEnzResult`, `BrendaData`, `PhylDist`, `FluxData`, `Enzyme` |
| Build steps of `make_ec_model` | `geckopy.ec_model.pipeline.add_protein_usage_reactions` and the other steps that `makeEcModel` runs inline |
| Algorithms | `relax_enz_concs` (least total fold increase of the enzyme bounds in one linear program), `level_complex_abundances` (one abundance per complex), `sweep_tunable_mask_size` and `recommend_target_impact_share` (share of kcats that `cmaes_kcat_tuning` tunes) |
| Algorithms | `level_complex_abundances` (one abundance per complex), `sweep_tunable_mask_size` and `recommend_target_impact_share` (share of kcats that `cmaes_kcat_tuning` tunes) |

## Differences in behaviour

The scenarios of the [raven-gecko-parity](https://github.com/CompMetEng/raven-gecko-parity) repository run both implementations on the same input and compare the results. The ledger of that repository records two differences as checkpoints, and further differences in the notes of single rows.

- **`ecFSEOF` and `ec_fseof`** return the same target reactions on ecTestGEM. On the ecYeastGEM of the tutorial the order of targets differs in 27 positions, and the set of targets depends on the solver pair, because the pFBA solution that the regression uses is not unique. On ecYeastGEM 9.1.1 the order is the same.
- **`upgradeGECKOproject` and `upgrade_project`** differ for a project that has an adapter class and no `model_adapter.toml`. `upgradeGECKOproject` converts the class. `upgrade_project` lists the adapter for conversion by hand, because an adapter class is MATLAB code, and then skips the conversion of the custom kcats and the stored predictions.
- **`sigmaFitter` and `fit_sigma`** scan the same grid of 0.01 steps. `sigmaFitter` returns the smallest sigma within a relative 1e-9 of the smallest error, and `fit_sigma` takes the first grid point with the smallest error, so solver rounding noise on a growth plateau can move its result to a later grid point. `fit_sigma` with `method="bisect"` returns a continuous sigma.
- **`sigmaFitter` and `fit_sigma`** scan the same grid of 0.01 steps. `sigmaFitter` returns the smallest sigma whose growth rate differs from the target by at most the smallest difference plus 1e-9 times the growth rate at the smallest difference, and `fit_sigma` takes the first grid point with the smallest error, so solver rounding noise on a growth plateau can move its result to a later grid point. `fit_sigma` with `method="bisect"` returns a continuous sigma.
- **`saveEcModel` and `save_ec_model`** write files that differ in charge, SBO terms, gene names and the subsystem of the protein usage reactions, because the models in memory differ in these fields; the layout of the files agrees.

## See also
Expand Down
Loading
Loading