Skip to content

feat: make the GECKO 4 kcat and proteomics workflow the default route - #33

Open
edkerk wants to merge 63 commits into
developfrom
feat/gecko4-workflow
Open

edkerk wants to merge 63 commits into
developfrom
feat/gecko4-workflow

Conversation

@edkerk

@edkerk edkerk commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

These changes take GECKO 3 steps that GECKO 4 replaced out of the usual workflow, and align MATLAB with geckopy. They are grouped because the rewritten guide (CompMetEng/gecko-docs#44) describes them together. geckopy: CompMetEng/geckopy#92. Parity ledger: CompMetEng/raven-gecko-parity#155.

Main improvements in this PR:

  • Changes for GECKO 3 users (each listed on the migration page):
    • updateProtPool, mergeDLKcatAndFuzzyKcats: no longer part of the workflow (updateProtPool failed on every ecModel made with GECKO 3.2.0 or later); moved to src/deprecated with a deprecation warning.
    • truncateValues: removed; nothing called it.
    • applyCustomKcats: replaced by data/kcats/custom.tsv; moved to src/deprecated. collectKcats and assignKcats raise collectKcats:legacyCustomKcats on a project that has only data/customKcats.tsv, and name convertCustomKcats.
    • runDLKcat, writeDLKcatInput, readDLKcatOutput: local functions of kcatsFromDLKcat ('via', 'docker' and 'via', 'file'). The stubs in src/deprecated warn; runDLKcat and writeDLKcatInput then raise an error that names kcatsFromDLKcat, while readDLKcatOutput still reads its file.
    • bayesianSensitivityTuning, its helpers abc_max, getrSample and updateprior, and getcarbonnum and findMaxValue: stubs that raise GECKO:removedFunction and name the replacement (cmaesKcatTuning, fillCarbonNum, kcatsFromBrenda).
    • Adapter classes: createGECKOproject warns when it writes one, the first adapter class loaded in a MATLAB session warns GECKO:deprecatedAdapterClass unless it subclasses TomlAdapter, and adapterTemplate.m moves to src/deprecated; model_adapter.toml configures GECKO and geckopy, and convertAdapterToToml converts a class.
    • Each deprecation warning says that the function will be removed in a future release.
    • setProtPoolSize: did nothing on a model without prot_pool_exchange; it now raises setProtPoolSize:noPoolExchange.
    • sigmaFitter: accepted a target growth rate of 0 or below; it now raises sigmaFitter:growthRate.
    • flexibilizeEnzConcs: could lower an existing higher bound and ran without an iteration cap when perComplex was off; on an infeasible input it returned an empty result silently, and now warns flexibilizeEnzConcs:infeasible.
    • getConcControlCoeffs: continued after a first solve that was not optimal; it now raises an error.
    • relaxProteomicsGreedy: raised the iteration error even when the last allowed relaxation reached the target; it also returns the relaxed model as second output.
    • getComplexData: without a taxonomic id it failed with "output not assigned"; it now warns and returns an empty result.
    • loadConventionalGEM: the filename option appended .xml to a .yml name.
  • Features:
    • kcatsFromDLKcat: option via ('okp', 'file', 'docker'); without data/DLKcat.tsv it predicts with the DLKcat method of OpenKineticsPredictor, so the presets gecko_median and gecko_classic no longer need Docker. It returns [kcatList, done].
    • kcatsFromOKP: the OpenKineticsPredictor engine (submitOpenKineticsPredictor, fetchOpenKineticsPredictor, writeOpenKineticsPredictorInput, readOpenKineticsPredictorOutput) became local functions; resolveOkpApiKey stays public.
    • okp.method, [kcat_sources.okp] methods: the default is KinForm-H alone (was CataPro, and eight methods for the presets).
    • relaxEnzConcs: new; finds the least total relaxation of the measured enzyme concentrations in one LP, as geckopy relax_enz_concs.
    • constrainEnzConcs: option restrictTo, as geckopy.
    • getConcControlCoeffs: option method ('finite_difference', 'shadow_price'), as geckopy.
    • [uniprot] id, [kegg] id: defaulted to the identifiers of Saccharomyces cerevisiae, so a project for another organism silently downloaded yeast data. They are now empty; loadDatabases raises loadDatabases:noUniprotID when data/uniprot.tsv is missing, and an empty KEGG identifier skips KEGG with a warning.
    • kcatDecisions.tsv: column names are snake_case, as geckopy writes them.
    • createGECKOproject: writes a .gitignore with data/okpApiKey.txt; the GECKO repository ignores the file too.
  • Fixes:
    • [kcat_sources.<name>]: a table replaced the preset's settings for that source; it now overrides only the keys it sets.
    • cmaesKcatTuning, screenKcatLeverage: failed further on without any evotune data file; they now raise evotune:noData. A source in several trust groups took the last group; it now takes the first, as geckopy.
    • ecFSEOF: failed with an index error when production had no range to scan; it now raises ecFSEOF:noRange.
    • downloadUniProt: kept only reviewed entries, against the adapter default uniprot.reviewed = false.
    • loadAdapterParams: replaced an empty adapter value with the default.
    • findMetSmiles: queried PubChem for empty metabolite names.
    • sensitivityTuning: printed light-model progress after the target check, and printed "No growth increase" without the WARNING: label.
    • upgradeGECKOproject: pointed calls to updateprior to updatePrior, which does not exist; it now names cmaesKcatTuning, and also lists calls to the other removed GECKO 3 functions.
  • Documentation:
    • Help texts that described the code wrongly: constrainEnzConcs (pool use), getPfbaEnzymes (field name), getEnzymeUsage (capacity usage), reportEnzymeUsage (threshold), ecFSEOF (three output files), makeEcModel (light model), findMetSmiles (cache path), fuzzyKcatMatching (closest organism), convertCustomKcats (error message).
    • fuzzyKcatMatching, assignKcatValues, mergeKcats, getKcatAcrossIsozymes, getStandardKcat, removeStandardKcat: marked low-level in their help.
    • sensitivityTuning and cmaesKcatTuning are named the standard and the advanced kcat tuning.
  • Tutorials:
    • tutorials/full_ecModel, tutorials/light_ecModel: protocols rewritten for GECKO 4 without the GECKO 3 protocol steps. Both assign kcats with the brenda_ec_tree preset from shipped files in data/kcats and need no OpenKineticsPredictor key; models and outputs are regenerated. Stray files and HumanGEMAdapter.m are removed.

Instructions on merging this PR:

  • This PR has develop as target branch, and will be resolved with a squash-merge.
  • This PR has main as target branch, and will be resolved with a merge commit.

updateProtPool raises an error on every ecModel made with GECKO 3.2.0 or later; setProtPoolSize sets the protein pool for a condition. mergeDLKcatAndFuzzyKcats is a wrapper of mergeKcats. Both move to src/deprecated and print a deprecation warning. truncateValues had no caller in src.
createGECKOproject warns when it writes an adapter class, and adapterTemplate.m moves to src/deprecated. model_adapter.toml configures GECKO and geckopy; adapter classes still load, and convertAdapterToToml converts them.
kcatsFromDLKcat gets the option via: 'okp' predicts with the DLKcat method of OpenKineticsPredictor, 'file' reads data/DLKcat.tsv and 'docker' runs DLKcat locally in its Docker image. Without data/DLKcat.tsv the default is 'okp', so the presets gecko_median and gecko_classic no longer need Docker. updateKcatSources reports a dlkcat source as pending while its OKP job runs. 'run', true still selects the Docker run.
The GECKO repository ignores okpApiKey.txt, and createGECKOproject writes a .gitignore with data/okpApiKey.txt in a new project. The help of resolveOkpApiKey said the file was ignored, which was not the case.
Adds tc0701-tc0704 to geckoCoreFunctionTests so CI runs them.
The column sucrose (r_2058) appeared twice with the same values in every row.
A project that does not set [uniprot] id and [kegg] id no longer gets the identifiers of Saccharomyces cerevisiae. loadDatabases raises loadDatabases:noUniprotID when data/uniprot.tsv is missing and the UniProt identifier is empty; an empty KEGG identifier skips KEGG with a warning, as before. adapterTemplate.toml writes empty identifiers with examples.
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Unit test results

105 tests   105 ✅  18s ⏱️
  1 suites    0 💤
  1 files      0 ❌

Results for commit 2158fa2.

♻️ This comment has been updated with latest results.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant