Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
50 commits
Select commit Hold shift + click to select a range
0a8298a
feat: remove truncate_values, which nothing calls
edkerk Nov 11, 2026
e282eb5
feat: predict DLKcat kcats with OpenKineticsPredictor by default
edkerk Nov 11, 2026
0786e45
doc: name the standard and the advanced kcat tuning
edkerk Nov 11, 2026
c132e41
fix: keep the OpenKineticsPredictor API key file out of git
edkerk Nov 11, 2026
c24b4d3
doc: correct function help, module notes and the relaxation methods page
edkerk Nov 11, 2026
6d839b8
fix: return no complexes from get_complex_data without a taxonomic id
edkerk Nov 11, 2026
41621b3
fix: check the target after the last allowed greedy relaxation
edkerk Nov 11, 2026
5de0823
fix: raise in fit_sigma for a target growth rate of 0
edkerk Nov 11, 2026
2833c53
fix: leave the isozyme kcats of collect_kcats unapplied
edkerk Nov 11, 2026
b2b507d
fix: report both complex proposals of a reaction in apply_complex_data
edkerk Nov 11, 2026
1703cc4
feat: include unreviewed entries in uniprot-download by default
edkerk Nov 11, 2026
562ba29
fix: skip the kegg download in load_kegg_tsv without an organism code
edkerk Nov 11, 2026
907264b
feat: download missing uniprot and kegg files in make_ec_model
edkerk Nov 11, 2026
f040c80
feat: take precomputed complex families in level_complex_concs
edkerk Nov 11, 2026
6868d28
feat: return the default f factor without proteomics data
edkerk Nov 11, 2026
81968bf
feat: take method in the sigma_fitter alias
edkerk Nov 11, 2026
eecb088
fix: merge a kcat_sources table into the preset settings
edkerk Nov 11, 2026
f27b3f6
fix: raise in ec_fseof when there is no production range to scan
edkerk Nov 11, 2026
fbe0ad2
feat: label ec_fseof targets and build its gene targets as ecFSEOF
edkerk Nov 11, 2026
e475e3e
style: remove the unused pytest import of a parity test
edkerk Nov 11, 2026
a1156c2
fix: raise in get_conc_control_coeffs on a model without optimal solu…
edkerk Nov 11, 2026
60970a5
fix: include unreviewed uniprot entries by default as the adapter does
edkerk Nov 11, 2026
ca90d5a
doc: name the current gecko paths and the matlab greedy relaxation
edkerk Nov 11, 2026
e2c4a01
feat: deprecate apply_custom_kcats and refuse the gecko 3 custom kcat…
edkerk Nov 11, 2026
0275828
feat: deprecate run_dlkcat and read_dlkcat_output
edkerk Nov 11, 2026
80f05e6
refactor: make the openkineticspredictor engine private
edkerk Nov 11, 2026
6f0eab4
doc: mark the low-level kcat functions in their docstrings
edkerk Nov 11, 2026
1c6663f
feat: use KinForm-H as the default okp method
edkerk Nov 11, 2026
b6d91b3
feat: use KinForm-H as the default OKP method of the presets
edkerk Nov 11, 2026
1644b67
feat: deprecate write_dlkcat_input in favour of kcats_from_dlkcat
edkerk Nov 11, 2026
9f539e7
fix: return converged false when greedy relaxation runs out
edkerk Nov 11, 2026
8142b55
fix: raise in fit_sigma for any growth rate not above 0
edkerk Nov 11, 2026
9862072
doc: state the okp methods of the preset comparison in collect_kcats
edkerk Nov 11, 2026
c9a6421
fix: refuse a GECKO 3 custom kcats file before changing the model
edkerk Nov 11, 2026
b4f4fce
feat: name replacements of removed functions in upgrade_project
edkerk Nov 11, 2026
725ac60
doc: predict dlkcat kcats with kcats_from_dlkcat in the full tutorial
edkerk Nov 11, 2026
de05622
feat: export EcFSEOFResult from geckopy
edkerk Nov 11, 2026
ec9bb27
fix: use the no-range tolerance of ecFSEOF in ec_fseof
edkerk Nov 11, 2026
746af93
test: keep the dlkcat okp test from submitting a real job
edkerk Nov 11, 2026
08fb08c
feat: leave the UniProt and KEGG identifiers empty by default
edkerk Nov 11, 2026
89d9b43
feat: remove the deprecated aliases with gecko 3 names
edkerk Nov 12, 2026
ef95b47
doc: drop the removed aliases from the docs and changelog
edkerk Nov 12, 2026
97839fe
Merge branch 'develop' into feat/gecko4-workflow
edkerk Nov 12, 2026
87e0303
feat: name the OKP methods only in [kcat_sources.okp] methods
edkerk Nov 16, 2026
64fff46
feat: give each evotune source group its own table, width and prefix …
edkerk Nov 16, 2026
9891191
feat: take the BRENDA aggregation of direct calls from [kcat_sources.…
edkerk Nov 16, 2026
ba6d496
feat: require gr_exp when a function needs it
edkerk Nov 16, 2026
abb8039
feat: reject unknown and malformed keys in model_adapter.toml
edkerk Nov 16, 2026
53e5d5b
feat: show the resolved adapter parameters
edkerk Nov 16, 2026
5ecd3cc
Merge branch 'develop' into feat/adapter-params
edkerk Nov 16, 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
9 changes: 8 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,14 @@
* `upgrade_project` (`geckopy upgrade`) reports the calls of removed or replaced functions in the project's scripts with their replacement, for example `submit_open_kinetics_predictor`, `fetch_open_kinetics_predictor`, `build_okp_input_csv` and `truncate_values`.
* The deprecated aliases with GECKO 3 names are removed from `geckopy`: `run_dlkcat`, `read_dlkcat_output`, `write_dlkcat_input`, `apply_custom_kcats`, `get_kcat_across_isozymes`, `get_standard_kcat`, `select_kcat_value`, `merge_dlkcat_and_fuzzy_kcats`, `get_ec_from_database`, `get_ec_from_gem`, `sigma_fitter` and `constrain_flux_data`, and `find_max_value`, which ports `findMaxValue` that GECKO 4 removed. `upgrade_project` (`geckopy upgrade`) reports each of them in a project's scripts with its replacement, which `geckopy.upgrade.RENAMED` lists. `extract_enzyme_substrate_pairs` stays public.
* The `okp` source group of the presets is the OpenKineticsPredictor method KinForm-H alone by default, instead of the eight methods with combination parameters; a project that sets `[kcat_sources.okp] methods` keeps its list. `update_kcat_sources` then gathers `okp_kinform_h.tsv` only. GECKO uses the same default.
* The default of `okp.method` (the OpenKineticsPredictor method of `kcats_from_okp` without `method`) is `KinForm-H` instead of `CataPro`, as in GECKO.
* `okp.method` is removed from model_adapter.toml; `[kcat_sources.okp] methods` is the only setting that names OpenKineticsPredictor methods (default `["KinForm-H"]`). `kcats_from_okp` without `method` uses the first entry of `methods`; it used `okp.method`. `[kcat_sources.okp_<x>] method` is removed: the method of the file `okp_<x>` is the known method whose file name is `okp_<x>` (`okp_` and the method in lower case, each run of other characters than letters and digits as `_`), and `update_kcat_sources` reports any other `okp_<x>` as failed (`<name> is not the file of a known OKP method; the files are ...`). `Unknown OKP methods in [kcat_sources.okp] methods: ...` lists the names comma-separated. `CatPred` and `TurNup` are no longer accepted in `[kcat_sources.okp] methods`: `kcats_from_okp` rejects them, so the configuration now fails early with `Unknown OKP methods`.
* Evotune source groups are one table each, `[evotune.source_groups.<group>]` with `sources` and `sigma0_log`, both required. `[evotune.sigma0_log_source]` and `SourceGroupRule.match_okp` are removed, and so is the `okp_method` argument of `classify_kcat_source`, `classify_kcat_sources`, `screen_kcat_leverage`, `cmaes_kcat_tuning`, `sweep_tunable_mask_size` and the other tuning functions; a group covers OpenKineticsPredictor kcats with a pattern such as `okp_*`. `sigma0_log` is a standard deviation of the natural log of the kcat. A `sources` entry ending in `*` is a prefix pattern on the origin (case-insensitive); exact matches over all groups are tried first, then patterns, the longest prefix first, and groups of equal length in file order. Without `[evotune.source_groups]` the groups are `custom` 0.1, `brenda` 0.2, `ec_tree` 0.3 and `combined` 0.4 (they were `dlkcat` 0.4, `brenda` 0.2 and `custom` 0.1); groups in the file replace the defaults entirely. Tuning warns when more than 20 % of the tunable kcats are in no group: `<n> of <m> tunable kcats match no evotune source group and get sigma0_log_default (<value>); origins: <up to 5, by count descending and then by name>`.
* `kcat_aggregate_brenda` is removed from model_adapter.toml (and `ModelParameters`); `[kcat_sources.brenda] aggregation` is the only BRENDA aggregation setting. `kcats_from_brenda` and `fuzzy_kcat_matching` without an explicit aggregation use it as the kcat assignment config resolves it: median for the default preset `brenda_ec_tree` and the other median presets, max for `gecko_classic`, and max when neither the preset nor the file sets it. They used `kcat_aggregate_brenda`, which defaulted to `"max"`, so a call without an aggregation under the default preset now takes the median.
* `kcat_aggregate_candidates` and `kcat_aggregate_isozymes` are removed from model_adapter.toml (and `ModelParameters`). `apply_kcat_list` takes `criteria="max"` and `fill_kcats_from_isozymes` takes `aggregate="mean"` as their defaults, as before; they no longer read an adapter value.
* `gr_exp` has no default (it was `0.41`, the yeast growth rate). `sensitivity_tuning`, `fit_sigma`, `flexibilize_enz_concs` and `relax_enz_concs` called without a growth rate raise `ValueError: gr_exp is not set in model_adapter.toml` when the file does not set it; `geckopy init` writes it commented out, noting that the functions that tune kcats or fit sigma require it. A project that relied on `0.41` sets `gr_exp`.
* An unknown key in model_adapter.toml is an error, whatever its place: `ModelAdapter.from_folder` raises `ValueError` with `<file>: unknown key <dotted.key> in model_adapter.toml`. This includes keys under `evotune.source_groups.<group>`, the `kcat_assignment.stage` entries and `kcat_sources.<name>`. The keys of `[kcat_sources.<name>]` are `aggregation` and `force_wildcard_level` for `brenda`, `k` for `ec_tree`, `k`, `min_identity` and `coverage` for `homologs`, `methods` for `okp`, and none for `custom`, `dlkcat` and `okp_<file of a known OKP method>`; another source name is an unknown key. A malformed evotune group raises `<file>: evotune.source_groups.<g> must be a table with sources and sigma0_log`, `... needs both sources and sigma0_log`, `... .sources must be a list of strings` or `... .sigma0_log must be a positive number`. The removed keys are unknown keys: no alias or warning remains for them.
* `geckopy adapter show [FOLDER]` (default: the current folder) and `show_adapter_params(adapter)` print one line per item in the order of `adapterParameters.tsv`: `<key> = <value> [<origin>]` with the origin `file`, `default`, `preset <name>` or `not set` (`<key> = [not set]`), without a header. The kcat assignment stages (`kcat_assignment.stage[<i>]`), the `kcat_sources.<name>.<key>` settings and the evotune source groups with their `sigma0_log` are shown as resolved. GECKO has `showAdapterParams`.
* `ModelAdapter.from_folder` checks more of model_adapter.toml when it loads it: `[kcat_sources.okp] methods` must be a list of strings and name known OKP methods (`Unknown OKP methods in [kcat_sources.okp] methods: <names in file order, once each>; methods: <known>.`), a `[kcat_sources]` entry must be a table (`<file>: kcat_sources.<name> must be a table`), `[kcat_sources.brenda] aggregation` must be `max` or `median`, an evotune group's `sources` must be a non-empty list of strings, and `sigma0_log` must be finite and positive. A function given another BRENDA aggregation raises `aggregation must be max or median`. The unlabelled-kcat warning of evotune tuning is also issued as a `UserWarning`. `geckopy adapter show` prints whole-valued numbers without decimals and lists the `kcat_sources` settings by source (brenda, ec_tree, homologs, okp, then others alphabetically) and key.
* `submit_open_kinetics_predictor`, `fetch_open_kinetics_predictor`, `build_okp_input_csv` and `parse_okp_output` are private (`_submit_open_kinetics_predictor` and so on) and no longer exported from `geckopy`, `geckopy.gather_kcats` or `geckopy.gather_kcats.open_kinetics_predictor`: `kcats_from_okp` and `kcats_from_dlkcat(via="okp")` submit and fetch OpenKineticsPredictor jobs. GECKO moves its OKP engine functions into `kcatsFromOKP` in the same way. `OKPClient` and `OKPError` stay public.
* `convert_custom_kcats` (or `geckopy upgrade`) turns `data/customKcats.tsv` into `data/kcats/custom.tsv`. `collect_kcats` and `assign_kcats` do not apply `data/customKcats.tsv`: when a stage lists custom, `data/kcats/custom.tsv` does not exist and `data/customKcats.tsv` does, they raise `ValueError` naming `convert_custom_kcats`, before they change the model. The decisions have no stage `custom`. GECKO's `collectKcats` does the same.
* `download_uniprot` and `load_uniprot_tsv` download reviewed and unreviewed entries by default (`reviewed=False`), as the adapter default `uniprot.reviewed = false`; they downloaded reviewed entries only.
Expand Down
33 changes: 18 additions & 15 deletions docs/evotune_kcat_tuning.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,31 +86,34 @@ sigma0_log_default = 0.3 # trust for any source not listed below
max_growth_weight = 2.0 # weight the growth-rate data double against flux data

[evotune.source_groups.okp]
sources = ["OpenKineticsPredictor"]
match_okp = true
sources = ["okp_*"] # a trailing * is a prefix pattern on the origin
sigma0_log = 0.25

[evotune.source_groups.brenda]
sources = ["brenda"]
sigma0_log = 0.2

[evotune.source_groups.custom]
sources = ["custom"]

[evotune.sigma0_log_source]
okp = 0.25
brenda = 0.2
custom = 0.1
sigma0_log = 0.1
```

What each knob means:

- **Trust tiers** (`source_groups` + `sigma0_log_source` +
`sigma0_log_default`). Group your kcats by how much you trust their
origin, and give each group a standard deviation in log-space:
smaller means more trusted, and the search needs stronger evidence
before it moves that kcat far. `custom` (curated by hand) at 0.1 is
three times more trusted than an unlabelled prediction at 0.3. This
is the one section with no universal default -- your model's own
source labels determine it.
- **Trust tiers** (`source_groups` + `sigma0_log_default`). Group your
kcats by how much you trust their origin. Each group is one table
with `sources`, the `ec.source` labels it covers, and `sigma0_log`,
the standard deviation of the natural log of the kcat: smaller means
more trusted, and the search needs stronger evidence before it moves
that kcat far. `custom` (curated by hand) at 0.1 is three times more
trusted than a kcat in no group at 0.3 (`sigma0_log_default`). A
`sources` entry ending in `*` is a prefix pattern on the origin
(`okp_*` covers `okp_kinform_h` and `okp_eitlem_kinetics`); exact
entries are tried first over all groups, then patterns, the longest
prefix first. Without `[evotune.source_groups]` the groups are
`custom` 0.1, `brenda` 0.2, `ec_tree` 0.3 and `combined` 0.4; groups
in the file replace them. When more than 20 % of the tunable kcats
are in no group, tuning warns and names the most common origins.
- **`max_growth_weight`** (default `1.0`). The combined score is
`(rmse_flux + w * rmse_max_growth) / (w + 1)`. At `2`, growth-rate
error counts double against flux error -- useful when growth rate is
Expand Down
2 changes: 1 addition & 1 deletion docs/future_improvements.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ keep an in-flight release on schedule.
a range (e.g. `"0.1-2.5"`) is collapsed to its upper bound
unconditionally in `parse_brenda_json`. After the kcat-aggregation
refactor moved the rest of the pipeline to be configurable
(`kcat_aggregate_brenda = "max" | "median"`), this is the one
(`[kcat_sources.brenda] aggregation = "max" | "median"`), this is the one
residual max-leaning step. Honouring the adapter setting here
would make every layer consistent. Small effect (only rows
reported as ranges) — deferred.
Expand Down
18 changes: 10 additions & 8 deletions docs/kcat_aggregation.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,14 @@ 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
them into `BrendaData.kcat_max` / `.kcat_median` (and `.sa_*`) so
consumers never see doubled-up rows. The default
(`kcat_aggregate_brenda = "max"` on `ModelParameters`) preserves
MATLAB-GECKO behaviour; flipping that field to `"median"` (or passing
`fuzzy_kcat_matching(aggregate="median")` per call) makes both
aggregation layers — the per-triple snapshot view and the per-EC
runtime collapse — use median together.
consumers never see doubled-up rows. The setting
`[kcat_sources.brenda] aggregation` chooses between them: the default
preset `brenda_ec_tree` uses `"median"`, and `gecko_classic` uses `"max"`,
which is the GECKO 3 behaviour. A call such as `kcats_from_brenda` or
`fuzzy_kcat_matching` without an explicit aggregation takes that value
(`fuzzy_kcat_matching(aggregate="max")` overrides it per call). Either
value makes both aggregation layers — the per-triple snapshot view and
the per-EC runtime collapse — use the same aggregation together.

This document quantifies the two layers separately by walking the raw
BRENDA JSON (BRENDA release 2026.1, ~57 900 raw kcat rows, ~39 000
Expand Down Expand Up @@ -56,7 +58,7 @@ triples to a single per-EC kcat. There are four possible
|---|---|---|---|
| max | max | **maxmax** | historical default (MATLAB GECKO) |
| max | median | **maxmed** | the runtime-only median flag we had before |
| median | median | **medmed** | adapter `kcat_aggregate_brenda="median"` |
| median | median | **medmed** | `[kcat_sources.brenda] aggregation = "median"` |
| median | max | medmax | unused; included for symmetry |

`log10` spreads:
Expand All @@ -81,7 +83,7 @@ typical BRENDA assay; for 8.6 % it is ≥ 1 000× above. Most of that
comes from the runtime aggregation layer (`maxmax / maxmed` ≈ 1.38),
with a small further bias from the snapshot layer (`maxmed / medmed`
≈ 0.06). Both swap together when the user sets
`kcat_aggregate_brenda = "median"`.
`[kcat_sources.brenda] aggregation = "median"`.

| EC | n | max [1/s] | median [1/s] | max / median |
|---:|---:|---:|---:|---:|
Expand Down
8 changes: 5 additions & 3 deletions docs/migrating_from_gecko_matlab.md
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@ Each row maps a MATLAB function to its geckopy equivalent. The
| `applyKcatConstraints` | `apply_kcat_constraints` | **`[3→4]`** Writes coefficients with the forward-direction `usage_prot_*` / `prot_pool_exchange` convention. |
| `findMetSmiles` | `find_met_smiles` | **`[Py]`** Asynchronous PubChem cache via `requests`; uses a TSV cache (`data/smilesDB.tsv`) so re-runs are offline. |
| `getComplexData` | `get_complex_data` | — |
| `getKcatAcrossIsozymes` | `fill_kcats_from_isozymes` | **`[Py]`** Renamed. Aggregation strategy (`max` / `median` / `mean`) is adapter-configurable via `kcat_aggregate_isozymes`. |
| `getKcatAcrossIsozymes` | `fill_kcats_from_isozymes` | **`[Py]`** Renamed. The `aggregate` argument (`mean`, `median` or `max`) defaults to `mean`. |
| `getReactionsFromEnzyme` | `get_reactions_from_enzyme` | **`[Py]`** Returns one `DataFrame` instead of five parallel cells. |
| `setKcatForReactions` | `set_kcat_for_reactions` | Matches IDs without regard to letter case, ignores an unknown ID and does not apply the constraints unless `apply=True`, as `setKcatForReactions`; a light-model row is addressed by its `###_` ID. |
| `setProtPoolSize` | `set_prot_pool_size` | **`[3→4]`** Sets the **upper** bound of `prot_pool_exchange` (forward direction). |
Expand Down Expand Up @@ -422,8 +422,10 @@ JSON; bare EC numbers, plain organism names, `#` release header,
`references` column). GECKO 3's `max_KCAT.txt` etc. are no longer
read. **`[Py]`** geckopy additionally includes both **max** and
**median** rows per (ec, substrate, organism) triple in one file,
distinguished by an `aggregation` column. The default
`kcat_aggregate_brenda = "max"` preserves MATLAB-GECKO behaviour.
distinguished by an `aggregation` column. The
setting `[kcat_sources.brenda] aggregation` chooses one: the default
preset `brenda_ec_tree` uses `"median"`; `gecko_classic` uses `"max"`, the
GECKO 3 behaviour.
See [kcat_aggregation.md](kcat_aggregation.md).

---
Expand Down
5 changes: 3 additions & 2 deletions src/geckopy/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

The most-used names, grouped by stage of a typical workflow:

- **Project setup**: ``ModelAdapter``
- **Project setup**: ``ModelAdapter``, ``show_adapter_params``
- **Build**: ``load_conventional_gem``, ``make_ec_model``
- **Enrich kcats**: ``update_kcat_sources`` (``kcats_from_brenda``,
``kcats_from_dlkcat``, ``kcats_from_okp``, ...), ``collect_kcats``,
Expand Down Expand Up @@ -38,7 +38,7 @@
__version__ = "0.0.0+unknown"

# Adapter
from geckopy.adapter import ModelAdapter, ModelParameters
from geckopy.adapter import ModelAdapter, ModelParameters, show_adapter_params

# Databases (loaders + dataclasses)
from geckopy.databases import (
Expand Down Expand Up @@ -171,6 +171,7 @@
# Adapter
"ModelAdapter",
"ModelParameters",
"show_adapter_params",
# Core data + builder + per-enzyme accessor
"EcData",
"EcModel",
Expand Down
6 changes: 5 additions & 1 deletion src/geckopy/adapter/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,18 @@
ModelParameters,
UniprotParams,
)
from .resolve import resolve_adapter, resolve_param
from .resolve import resolve_adapter, resolve_gr_exp, resolve_param
from .show import format_adapter_params, show_adapter_params

__all__ = [
"ComplexParams",
"KeggParams",
"ModelAdapter",
"ModelParameters",
"UniprotParams",
"format_adapter_params",
"resolve_adapter",
"resolve_gr_exp",
"resolve_param",
"show_adapter_params",
]
4 changes: 3 additions & 1 deletion src/geckopy/adapter/adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
from pathlib import Path
from typing import TYPE_CHECKING

from .params import ModelParameters
from .params import ModelParameters, check_adapter_keys

if TYPE_CHECKING:
import cobra
Expand Down Expand Up @@ -82,6 +82,8 @@ def from_folder(cls, folder: str | Path) -> "ModelAdapter":
with open(config_path, "rb") as f:
data = tomllib.load(f)

check_adapter_keys(data, config_path)

# The path field is injected from the folder location, not the TOML,
# so that the TOML file is location-independent.
data["path"] = folder
Expand Down
Loading
Loading