[edkerk]

Kcat strategies for different users, BRENDA from toolbox-assets, and upgrades of GECKO 3 projects. geckopy has the same (CompMetEng/geckopy#68). 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). kcatAssignmentConfig gives each stage's expanded files and okpMethods.

combine stage. 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. model.ec.source reads combined (sd=0.61, n=6), and the decisions get sdLog10. A source without parameters is an error.

OKP. readOpenKineticsPredictorOutput keeps the max similarity to <method> training data column as similarity, kcatsFromOKP writes it as similarity= in the detail column, and loadKcatSource 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

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

1. the enzyme–substrate pairs of each reaction, as DLKcat uses them (extractEnzymeSubstratePairs);
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's DIAMOND (downloaded by downloadRavenBinaries 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; updateKcatSources gathers it. extractEnzymeSubstratePairs is the substrate rule of writeDLKcatInput, now a function of its own that writeDLKcatInput calls.

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

GECKO no longer ships BRENDA data. fetchBrendaAsset downloads the files of the toolbox-assets release brenda-2026.1-1 (BRENDA 2026.1, CC BY 4.0) on first use, with RAVEN's fetchToolboxAsset, into databases/brenda-2026.1-1, and unpacks them:

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

ModelAdapter.getBrendaDBFolder gives the project's data/brenda when it exists (written by geckopy brenda-refresh) and these files otherwise. The files have the same content as those databases/ held.

Upgrading GECKO 3 projects

• convertCustomKcats(ecModel) writes data/customKcats.tsv as the curated source file data/kcats/custom.tsv: the kcats applyCustomKcats 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.

• upgradeEcModel turns the protein usage and pool reactions of a GECKO 3 ecModel forward (#419): stoichiometry, bounds and objective coefficient change sign; models already forward are left as they are.

• upgradeGECKOproject(projectPath) lists, and with 'dryRun', false carries out:

  1. adapter class → model_adapter.toml (convertAdapterToToml), listing methods to carry over by hand;
  2. customKcats.tsv → data/kcats/custom.tsv;
  3. stored DLKcat and OKP results → source files, without running anything;
  4. saved GECKO 3 ecModels in models/ turned forward;
  5. project_format = 4 in model_adapter.toml;
  6. script lines that call renamed or replaced functions, listed, not changed.

  Steps 2 and 3 need the full ecModel ('ecModel'); without it they are listed and skipped. Originals go to legacy/<date>/; steps already done are left out, so it can run again.

• model_adapter.toml takes project_format.

keggPhylDist.mat in RAVEN 3

RAVEN 3 keeps keggPhylDist.mat under src/reconstruction/kegg. ModelAdapter.getPhylDistStructPath looks there first, then under reconstruction/kegg (earlier RAVEN 3) and external/kegg (RAVEN 2).

Tutorial

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

Tests

Test file	Cases
combineTests (tc0088–tc0090)	a hand-computed combination for okp and ec_tree_okp; errors for a method without parameters and an unknown method
ecTreeTests (tc0085, tc0087)	the BRENDA release download; the default preset's order
homologsTests (tc0095–tc0097)	a fixture of known identities (an exact copy, an 80% copy, an unrelated sequence): the estimate, k and minIdentity; substrate matching by ChEBI annotation; the homolog presets
upgradeTests (tc0091–tc0094)	convertCustomKcats keys and overlap; the same kcats before and after conversion; upgradeEcModel both ways; upgradeGECKOproject dry run, run and rerun

On the yeast tutorial model, GECKO and geckopy give the same kcats, labels and uncertainties with ec_tree_okp on the same EC-tree and OKP files, and convertCustomKcats 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, kcatsFromOKP and geckopy's kcats_from_okp write identical source files (4,126 rows for DLKcat, 4,205 for the others).

[github-actions]

Unit test results

61 tests   61 ✅  8s ⏱️
 1 suites   0 💤
 1 files     0 ❌

Results for commit b9669ed.

♻️ This comment has been updated with latest results.