Assign kcats from the kcat source files, as model_adapter.toml sets

[edkerk]

Kcats are assigned from the kcat source files in data/kcats (#64), in an order that model_adapter.toml sets. GECKO has the same functions and settings (CompMetEng/GECKO#9). This is step K2 of the plan in CompMetEng/raven-gecko-parity#134.

Builds on #61 (shared model_adapter.toml) and #64 (kcat source files); the diff shows their changes until they are merged.

Functions

Function	Does
collect_kcats	Decides one kcat per reaction from the source files on a copy of the model; returns the decisions, a report and the copy, and writes output/<model id>_kcatDecisions.tsv (stage, source, kcat, number of values and their spread per reaction)
assign_kcats	The same in place, then applies the kcat constraints. Replaces merge_kcats → apply_kcat_list → apply_custom_kcats → fill_kcats_from_isozymes → assign_standard_kcat → apply_kcat_constraints, which stay callable
update_kcat_sources	Gathers the source files the configuration needs (kcats_from_brenda, kcats_from_dlkcat, kcats_from_okp) when they are missing, or when their header records other settings or another BRENDA release than asked; dry_run=True only reports

Configuration

[kcat_assignment] and [kcat_sources.<name>] in model_adapter.toml, validated by KcatAssignmentParams and KcatStageParams; adapterParameters.tsv is the same file as GECKO's.

[kcat_assignment]
preset = "gecko_median"   # the default; or gecko_classic
isozymes = true
standard = true

# instead of a preset:
[[kcat_assignment.stage]]
sources = ["custom", "database_top", "dlkcat", "database_bottom"]
top_origin_limit = 4

• A stage decides the reactions that are still open, by the first listed source with a value (merge_kcats). Sources are source file names and the BRENDA tiers database_exact, database_top and database_bottom, which read brenda.tsv.
• A listed source file that does not exist is reported and left out. Without data/kcats/custom.tsv, data/customKcats.tsv is applied as before.

Presets

Preset	Order	BRENDA value
gecko_median (default)	custom → BRENDA without EC wildcards, origin 1–4 → DLKcat → other BRENDA matches (EC wildcards; specific activities, origin 5–6)	median
gecko_classic	custom → BRENDA without EC wildcards, origin 1–6 → DLKcat → other BRENDA matches	maximum

The order of gecko_median comes from comparing each BRENDA tier with DLKcat on measured kcats hidden from the search: the BRENDA median was as close or closer at every origin without wildcards, and the maximum was further off than the median in every tier. Specific-activity matches rank below DLKcat as in #58. The figures are in CompMetEng/raven-gecko-parity#134.

Tutorial

full_ecModel uses kcats_from_brenda, kcats_from_dlkcat and assign_kcats for STEP 18–31. Its model_adapter.toml gives the gecko_median stages, and kcats_from_brenda takes the BRENDA maximum from kcat_aggregate_brenda, so the ecModel is identical to the one the previous steps gave: 4842 ec.rxns, the same ec.kcat, ec.source and stoichiometry.

Tests

tests/test_kcat_assignment.py: both presets against the chain of functions they replace, collect_kcats leaving the model unchanged, custom.tsv deciding first, stages from TOML and their errors, and update_kcat_sources gathering missing and outdated files only. The new functions are exported from geckopy and geckopy.gather_kcats and listed in docs/migrating_from_gecko_matlab.md.