[edkerk]

Kcat strategies for different users, BRENDA from toolbox-assets, and upgrades of GECKO 3 projects. GECKO has the same (CompMetEng/GECKO#11). The plan is docs/kcat-strategies.md in CompMetEng/raven-gecko-parity#134.

Kcat strategies

Presets ([kcat_assignment] preset in model_adapter.toml):

Preset	Stages	For
brenda_ec_tree (default)	select(custom, the organism's own BRENDA value, EC tree) → combine(OKP) for the reactions left	most users
ec_tree_homologs	select(custom, own BRENDA value) → combine(EC tree, homologs) → combine(OKP)	measurements only, with homologs
ec_tree_okp	select(custom, own BRENDA value) → combine(EC tree, homologs, OKP) → combine(OKP)	measurements and predictions together
okp	select(custom) → combine(OKP)	users who do not trust the model's EC numbers
gecko_median, gecko_classic	BRENDA fuzzy matching and DLKcat, BRENDA median or maximum	earlier results

A single method is a stage: sources = ["custom", "okp_catapro"]. okp in a stage stands for the OpenKineticsPredictor methods of [kcat_sources.okp] methods (default: the eight methods that predict per enzyme–substrate pair and have combination parameters: CataPro, DLKcat, EITLEM, KinForm-H, KinForm-L, OmniESI, OmniESI-O2DENet and UniKP; CatRange has no parameters, and CatPred and TurNup need the whole reaction, so asking for them per pair is an error). update_kcat_sources gathers each method's file.

combine stage (geckopy.gather_kcats.combine_kcats). Each open reaction gets the precision-weighted mean of its sources' log10 values, each corrected for the source's bias and weighted by 1 / its error variance; both depend on the source's evidence for the reaction:

Source	Evidence bin
ec_tree	measurements of the full EC number (ec4:1-2 … ec4:>100), or the deepest EC level with measurements (ec3, ec2)
okp_<method>	the enzyme's similarity to the method's training sequences (<40, 40-60, 60-80, >80 %)
homologs	the identity of the nearest homolog

The uncertainty for a new measurement is sqrt(1 / Σ(1/variance) + 0.48²), scaled so the 80% interval covers 80% of the measurements the parameters were fitted on. The parameters (kcatCombineParams.tsv, in the BRENDA asset) were fitted on the kcat benchmark's development split; on its 3,095 development pairs combine_kcats gives the benchmark's own combination to 6×10⁻⁷ log10. ec.source reads combined (sd=0.61, n=6), and the decisions get sd_log10. A source without parameters is an error.

OKP. parse_okp_output keeps the max similarity to <method> training data column as similarity, kcats_from_okp writes it as similarity= in the detail column, and load_kcat_source passes the detail on.

Why. Against measured kcats hidden from the sources (the enzyme's own measurements and those of sequences at ≥ 95% identity hidden):

• where the EC tree has nothing EC-specific, the OKP methods combined were closer than its fallback (−0.32 log10, −0.63 to −0.06; 31 pairs), DLKcat alone was not;
• the EC tree combined with the OKP methods was slightly closer than the EC tree (−0.026), and the OKP methods combined as close as the EC tree (+0.009);
• in ecModels, values combined with predictions set high-turnover enzymes such as ATP synthase too low, so the default uses predictions only where there is no value from measurements.

Homologs

kcats_from_homologs estimates kcats from measured homologs of the model's enzymes:

1. the enzyme–substrate pairs of each reaction, as DLKcat uses them (extract_enzyme_substrate_pairs);
2. each substrate's InChIKey (without the protonation flag) from substrates.tsv of the BRENDA files: ChEBI annotations, then MetaNetX annotations, then the name (lower case, letters, digits and + only);
3. a search of each enzyme with raven-toolbox's DIAMOND (resolve_binary, downloaded when missing) against sequences.fasta of the BRENDA files: at least 40% identity, 80% coverage of both sequences;
4. per enzyme and substrate, the identity-weighted mean of the median kcats of up to 10 homologs measured on that substrate; for an enzyme complex, the median over its subunits;
5. a homolog at 95% identity or more is a measurement of (nearly) the same protein: when there is one, the estimate is the median of those alone, and the combination gives it the exact bin of kcatCombineParams.tsv (bias 0, the smallest error variance). That bin is an assumption, stated in the file: the benchmark the other bins were fitted on hides homologs above 95% identity. On the yeast tutorial model 73 homolog values come from an identical sequence.

The values go to data/kcats/homologs.tsv, with identity= (nearest homolog, three decimals as DIAMOND reports it) and n= (homologs used) in the detail column; update_kcat_sources gathers it. extract_enzyme_substrate_pairs also returns each substrate's met_id.

DIAMOND gives the same homologs as the MMseqs2 search of the kcat benchmark: on the development split 99% of the hits are shared, identities agree within ±0.003, and the homolog estimate and its combination with the EC tree are as close to the hidden measurements (DIAMOND minus MMseqs2 +0.002 log10, −0.001 to +0.007). The estimate equals the benchmark's homolog strategy on its 1,863 development pairs with a homolog. On the yeast tutorial model, homologs give values for 352 reactions in 8 s, and GECKO and geckopy write the same 418 rows (the kcats agree to the last binary digit). With BRENDA alone, homologs add little to the EC tree (−0.002 log10, not significant), so they are in ec_tree_homologs and ec_tree_okp, not in the default.

BRENDA files from toolbox-assets

geckopy no longer ships BRENDA data. fetch_brenda_asset downloads the files of the toolbox-assets release brenda-2026.1-1 (BRENDA 2026.1, CC BY 4.0) on first use, with raven-toolbox's ensure_data_file (SHA-256 checked, cached), and unpacks them in the cache:

File	Used by
kcat.tsv, sa.tsv, mw.tsv	fuzzy matching (kcats_from_brenda)
measurements.tsv	EC tree (kcats_from_ec_tree)
sequences.fasta, substrates.tsv	homologs, substrate matching
kcatCombineParams.tsv	the combine stage

ModelAdapter.get_brenda_db_folder gives the project's data/brenda when it exists (written by geckopy brenda-refresh) and these files otherwise. Processes that download or unpack the same file at once use each other's result. The wheel carries no BRENDA files, so the build hook that compressed them is gone. kcats_from_brenda downloads PhylDist.mat when the project has none.

Upgrading GECKO 3 projects (geckopy.upgrade)

• convert_custom_kcats(ec_model) writes data/customKcats.tsv as the curated source file data/kcats/custom.tsv: the kcats apply_custom_kcats gives the ecModel, including which of two overlapping entries wins, one row per reaction keyed by conventional reaction and enzyme set. custom.tsv also applies to light ecModels.

• upgrade_ec_model turns the protein usage and pool reactions of a GECKO 3 ecModel forward; load_ec_model already does this for the files it reads.

• upgrade_project(path) and geckopy upgrade <folder> [--apply] [--ec-model FILE] list, and carry out:

  1. customKcats.tsv → data/kcats/custom.tsv;
  2. stored DLKcat and OKP results → source files, without running anything;
  3. saved GECKO 3 ecModels in models/ rewritten in the forward direction;
  4. project_format = 4 in model_adapter.toml;
  5. script lines that call renamed or replaced functions, listed, not changed.

  Steps 1 and 2 need the full ecModel; without it they are listed and skipped. The adapter-class step is GECKO's. Originals go to legacy/<date>/; steps already done are left out, so it can run again.

• model_adapter.toml takes project_format.

Tutorial

full_ecModel gives the same ecModel as before (4842 ec.rxns, same ec.kcat, ec.source and stoichiometry); a new section explains how to choose a kcat strategy and upgrade older projects.

ecModels GECKO can read

The enzyme and pool pseudometabolites carry their description as RAVEN's metabolite note (notes: Enzyme-usage pseudometabolite), as makeEcModel writes it. As a separate notes key it was saved as a nested map, which RAVEN's readYAMLmodel rejects, so GECKO could not load an ecModel saved by geckopy.

Tests

• tests/test_combine_kcats.py: evidence bins; a hand-computed combination; the okp and ec_tree_okp presets; errors.
• tests/test_ec_tree.py: the BRENDA release download; the default preset's order.
• tests/test_homologs.py: a fixture of known identities (an exact copy, an 80% copy, an unrelated sequence), shared with GECKO: the estimate, k and min_identity; compact names; substrate matching by ChEBI, MetaNetX and name; the homolog presets.
• tests/test_make_ec_model.py: the pseudometabolites' notes in the saved YAML.
• tests/test_upgrade.py: conversion keys and overlap; the same kcats before and after conversion; upgrade_ec_model; upgrade_project dry run, run, rerun and geckopy upgrade.

On the yeast tutorial model, geckopy and GECKO give the same kcats, labels and uncertainties with ec_tree_okp on the same EC-tree and OKP files, and convert_custom_kcats gives the same 219 rows in both tools and the same kcats as customKcats.tsv. On ecYeastGEM 9.1.1 with real OpenKineticsPredictor results of the eight default methods, kcats_from_okp and GECKO's kcatsFromOKP write identical source files (4,126 rows for DLKcat, 4,205 for the others), GECKO reading the model saved by geckopy. The suite passes from an empty cache with eight parallel workers.