Keep gathered kcats as kcat source files, one per source

[edkerk]

Copied from SysBioChalmers/GECKO#488, opened by edkerk on 2026-10-16.

Gathered kcats are kept in the project as kcat source files, one per source: data/kcats/<source>.tsv. Rows are keyed by conventional reaction and enzyme set, not by model.ec.rxns, so a file stays valid when the ecModel is rebuilt and applies to full and light models alike. geckopy reads and writes the same files (CompMetEng/geckopy#64). This is step K1 of the plan in CompMetEng/raven-gecko-parity#134.

Gathering, one function per source

Function	Gathers	Notes
kcatsFromBrenda	Fuzzy BRENDA matching (fuzzyKcatMatching)	Options aggregation, forceWClvl, ecRxns; the BRENDA release goes in the file header
kcatsFromDLKcat	DLKcat	With 'run', true it writes the input and runs the Docker image (checking that Docker is there, with runDLKcat's macOS path fix); otherwise it reads an earlier output. A run records the reactions it covered in data/DLKcat_run.txt
kcatsFromOKP	One OpenKineticsPredictor method	See below

OKP jobs per method

• Each method keeps its own job in data/OKP_job_<method>.txt and its own result in data/OKP_output_<method>.csv; the file is okp_<method>.tsv.
• Without a job for the method, it submits one. With a job, it fetches the result straight into the method's file, and writes the source file once the job is done.
• The job file records which job its stored result came from. 'useStored', true only uses a result of the current job, and 'resubmit', true removes the earlier result.
• A result that fetchOpenKineticsPredictor stored by itself (data/OKP_output.csv) is taken over only when its job is for the method and its predictions are labelled with that method.
• fetchOpenKineticsPredictor gets an outFile option for this.

Writing, for all three

• Each writes its file by default and returns the kcat list. 'save', false writes nothing; 'saveAs' names another file.
• With a subset (ecRxns) and the default name, a warning says the file is replaced.
• Options are name-value only, so a misspelled option is an error.

File functions

• saveKcatSource(model, kcatList, name) writes any kcat list:

  • UTF-8, LF line endings, rows sorted by every column;
  • a header with source, generator, settings (compact JSON with sorted keys, under the TOML parameter names), data version, kind and time;
  • rows with a kcat that is not a positive finite number, and rows of reactions without enzymes, are left out.

  It never writes custom.tsv, or a file whose header says kind: curated or source: custom, in any case.

• loadKcatSource(model, name) reads a file and maps its rows to model.ec: by reaction and enzyme set, by enzyme set only, or by reaction only.

  • Reading: a byte-order mark and CRLF are fine; comments and blank lines are skipped; fields a spreadsheet wrapped in quotes are unwrapped; numbers must be plain decimals, so 5,5 reads as missing instead of 55; a row with extra fields, or a duplicate or reserved column name, is an error.
  • It reports, with the file's line number: rows with an invalid kcat; rows that fit no reaction; rows that match at least half of an enzyme set (partial matches, not applied).
  • report.header and report.records give the header lines and the rows as read.

• getEcRxnKeys(model) gives the conventional reaction and enzyme set of every model.ec reaction.

Helpers are local functions of the functions that use them; there is no private folder.

Limit: for nested gene rules such as A and (B or C), the light model splits enzymes differently from the full model, so a file written from one may fit the other only partly; the unmatched rows are reported.

Tests: test/unit_tests/kcatSourceTests.m (tc0070–tc0078):

• keys of full and light models;
• round trips;
• full ↔ light files;
• matching rules;
• reactions without enzymes;
• the curated guard, including quoted lines and key case;
• invalid and infinite kcats;
• the parameter JSON (the same text geckopy's test expects);
• row order;
• the stored-result rules of kcatsFromOKP, including a result of another method and a result of an earlier job;
• a shared fixture file that geckopy's tests read too.

All unit tests pass (MATLAB R2023a, RAVEN develop, GLPK). At 60,000 reactions, getting the keys takes 0.8 s, saving 5.0 s and loading, reading included, 6.8 s. A file written by GECKO reads the same in geckopy and the other way round.

The functions that combine the source files into ec.kcat (collectKcats, assignKcats, updateKcatSources) follow in K2.

[github-actions]

Unit test results

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

Results for commit 4f06b59.

♻️ This comment has been updated with latest results.