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

docs/migrating_from_gecko_matlab.md

@@ -250,8 +250,11 @@ Each row maps a MATLAB function to its geckopy equivalent. The
 | `kcatsFromBrenda`                   | `kcats_from_brenda`                  | Fuzzy BRENDA matching, kept as `data/kcats/brenda.tsv`. Loads the BRENDA data and KEGG distances from the adapter unless passed in. |
 | `kcatsFromDLKcat`                   | `kcats_from_dlkcat`                  | DLKcat (run in Docker with `run=True`, or an earlier output), kept as `data/kcats/dlkcat.tsv`. |
 | `kcatsFromOKP`                      | `kcats_from_okp`                     | One OpenKineticsPredictor method, kept as `data/kcats/okp_<method>.tsv`; submits a job when there is none, writes the file once it is done. Returns `(kcat_list, done)`. |
-| `saveKcatSource`, `readKcatSource`, `loadKcatSource` | `save_kcat_source`, `read_kcat_source`, `load_kcat_source` | Kcat source files: one per source, keyed by conventional reaction and enzyme set, the same file format in both tools. `load_kcat_source` maps a file to the current model and reports rows that fit no reaction. |
+| `saveKcatSource`, `loadKcatSource` | `save_kcat_source`, `load_kcat_source`, `read_kcat_source` | Kcat source files: one per source, keyed by conventional reaction and enzyme set, the same file format in both tools. `load_kcat_source` maps a file to the current model and reports rows that fit no reaction. **`[Py]`** `read_kcat_source` reads a file without a model; GECKO gives the same in `loadKcatSource`'s `report.header` and `report.records`. |
 | `getEcRxnKeys`                      | `ec_rxn_keys`                        | Conventional reaction and enzyme set per `ec.rxns` entry. |
+| `collectKcats`                      | `collect_kcats`                      | Decides one kcat per reaction from the source files, as `[kcat_assignment]` in model_adapter.toml sets (preset `gecko_median`, the default, or `gecko_classic`, or stages), without changing the model. Writes `output/<model id>_kcatDecisions.tsv`. |
+| `assignKcats`                       | `assign_kcats`                       | `collect_kcats`, then sets `ec.kcat` and `ec.source` and applies the kcat constraints; replaces `merge_kcats` → `apply_kcat_list` → `apply_custom_kcats` → `fill_kcats_from_isozymes` → `assign_standard_kcat` → `apply_kcat_constraints`. In place. |
+| `updateKcatSources`                 | `update_kcat_sources`                | Gathers the source files the configuration needs that are missing, or outdated against `[kcat_sources.<name>]`; `dry_run` only reports. |
 
 ### 5.3 Get enzyme data (`src/geckomat/get_enzyme_data`)
 

src/geckopy/__init__.py

@@ -74,7 +74,9 @@
 # Gather-kcats
 from geckopy.gather_kcats import (
     apply_kcat_list,
+    assign_kcats,
     assign_standard_kcat,
+    collect_kcats,
     fetch_open_kinetics_predictor,
     fuzzy_kcat_matching,
     get_standard_kcat,  # deprecated; alias of assign_standard_kcat
@@ -91,6 +93,7 @@
     save_kcat_source,
     select_kcat_value,  # deprecated; alias of apply_kcat_list
     submit_open_kinetics_predictor,
+    update_kcat_sources,
     write_dlkcat_input,
 )
 
@@ -195,7 +198,9 @@
     "set_prot_pool_size",
     # Gather-kcats
     "apply_kcat_list",
+    "assign_kcats",
     "assign_standard_kcat",
+    "collect_kcats",
     "fetch_open_kinetics_predictor",
     "fuzzy_kcat_matching",
     "kcats_from_brenda",
@@ -210,6 +215,7 @@
     "run_dlkcat",
     "save_kcat_source",
     "submit_open_kinetics_predictor",
+    "update_kcat_sources",
     "write_dlkcat_input",
     # get_enzyme_data
     "copy_ec_to_gem",

src/geckopy/adapter/adapterParameters.tsv

@@ -32,5 +32,10 @@ okp.method	okp.method	"CataPro"	OpenKineticsPredictor method
 okp.handle_long_sequences	okp.handleLongSequences	"truncate"	How OpenKineticsPredictor handles sequences that are too long
 okp.include_similarity_columns	okp.includeSimilarityColumns	true	Return similarity to the method's training data
 okp.canonicalize_substrates	okp.canonicalizeSubstrates	true	Canonicalize substrate SMILES before prediction
+kcat_assignment.preset			Kcat assignment preset: gecko_median (used when neither preset nor stages are given) or gecko_classic
+kcat_assignment.isozymes		true	Fill reactions without a kcat from their isozymes after the stages
+kcat_assignment.standard		true	Give the remaining reactions the standard kcat
+kcat_assignment.stage			Stages instead of a preset: action, sources, criteria and BRENDA limits ([[kcat_assignment.stage]])
+kcat_sources			Settings per kcat source file, e.g. [kcat_sources.brenda] aggregation
 matlab.make_model_anaerobic	matlab.makeModelAnaerobic		MATLAB function that constrains the ecModel to anaerobic growth
 matlab.change_protein_biomass	matlab.changeProteinBiomass		MATLAB function that changes the protein content of the biomass

src/geckopy/adapter/params.py

@@ -100,6 +100,54 @@ class MatlabParams(BaseModel):
     )
 
 
+class KcatStageParams(BaseModel):
+    """One ``[[kcat_assignment.stage]]``: decides each reaction that is still
+    open by the first listed source with a value."""
+    model_config = ConfigDict(extra="forbid")
+
+    action: Literal["select"] = Field(default="select", description="What the stage does.")
+    sources: list[str] = Field(
+        min_length=1,
+        description=(
+            "Source file names (custom, dlkcat, okp_catapro, ...) and the BRENDA tiers "
+            "database_exact, database_top and database_bottom, which read brenda.tsv; "
+            "first listed wins."
+        ),
+    )
+    criteria: Literal["max", "min", "median", "mean"] = Field(
+        default="max", description="Among several values of one source for a reaction."
+    )
+    top_origin_limit: int = Field(default=4, description="Origin limit of database_top.")
+    bottom_origin_limit: int = Field(default=6, description="Origin limit of database_bottom.")
+    wildcard_limit: int = Field(default=3, description="Wildcard limit of database_bottom.")
+
+
+class KcatAssignmentParams(BaseModel):
+    """How kcats are assigned from the kcat source files (``collect_kcats``)."""
+    model_config = ConfigDict(extra="forbid")
+
+    preset: Optional[Literal["gecko_classic", "gecko_median"]] = Field(
+        default=None,
+        description=(
+            "Kcat assignment preset; gecko_median is used when neither a preset nor "
+            "stages are given."
+        ),
+    )
+    isozymes: bool = Field(
+        default=True, description="Fill reactions without a kcat from their isozymes after the stages."
+    )
+    standard: bool = Field(default=True, description="Give the remaining reactions the standard kcat.")
+    stage: list[KcatStageParams] = Field(
+        default_factory=list, description="Stages instead of a preset."
+    )
+
+    @model_validator(mode="after")
+    def _preset_or_stages(self) -> "KcatAssignmentParams":
+        if self.preset is not None and self.stage:
+            raise ValueError("[kcat_assignment] gives both a preset and stages; give one of the two.")
+        return self
+
+
 class SourceGroupRule(BaseModel):
     """One trust-tier entry in ``EvotuneParams.source_groups``.
 
@@ -323,4 +371,9 @@ class ModelParameters(BaseModel):
     evotune: EvotuneParams = Field(default_factory=EvotuneParams)
     okp: OkpParams = Field(default_factory=OkpParams)
     spontaneous: SpontaneousParams = Field(default_factory=SpontaneousParams)
+    kcat_assignment: KcatAssignmentParams = Field(default_factory=KcatAssignmentParams)
+    kcat_sources: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Settings per kcat source file, e.g. kcat_sources.brenda.aggregation.",
+    )
     matlab: MatlabParams = Field(default_factory=MatlabParams)

src/geckopy/gather_kcats/__init__.py

@@ -3,6 +3,7 @@
 Mirrors GECKO MATLAB's `src/geckomat/gather_kcats/` directory.
 """
 from .fuzzy_kcat_matching import fuzzy_kcat_matching
+from .kcat_assignment import assign_kcats, collect_kcats, update_kcat_sources
 from .kcat_sources import ec_rxn_keys, load_kcat_source, read_kcat_source, save_kcat_source
 from .kcats_from import kcats_from_brenda, kcats_from_dlkcat, kcats_from_okp
 from .get_standard_kcat import assign_standard_kcat, get_standard_kcat
@@ -28,7 +29,9 @@
     "OKPClient",
     "OKPError",
     "apply_kcat_list",
+    "assign_kcats",
     "assign_standard_kcat",
+    "collect_kcats",
     "ec_rxn_keys",
     "extract_enzyme_substrate_pairs",
     "fetch_open_kinetics_predictor",
@@ -49,5 +52,6 @@
     "save_kcat_source",
     "select_kcat_value",  # deprecated; alias of apply_kcat_list
     "submit_open_kinetics_predictor",
+    "update_kcat_sources",
     "write_dlkcat_input",
 ]