diff --git a/docs/gecko4-kcat-assignment.md b/docs/gecko4-kcat-assignment.md index e3e47f0..a5d25a6 100644 --- a/docs/gecko4-kcat-assignment.md +++ b/docs/gecko4-kcat-assignment.md @@ -12,6 +12,8 @@ GECKO 4 assigns the kcat of each reaction from kcat source files, in an order th | `assignKcats` | `assign_kcats` | applies the decisions and the kcat constraints. Kcats that the model had are replaced | | `updateKcatSources` | `update_kcat_sources` | gathers the source files that the configuration needs and that are missing or outdated | | `kcatAssignmentConfig` | `kcat_assignment_config` | returns the settings with the preset expanded into stages | +| `parseKcatSource` | `parse_kcat_source` | splits an entry of `ec.source` into its origin, detail, tuning methods and prior | +| `formatKcatSource` | `format_kcat_source` | writes an entry of `ec.source` from these parts | ## Sources @@ -63,6 +65,53 @@ A stage has the options `action` (default `select`), `sources`, `criteria` (defa Against measured kcats hidden from the search, the EC tree was closer than the BRENDA median at origin 2, at origin 4 and with EC wildcards, and as close at origin 1 and 3. The EC tree combined with the OKP methods was slightly closer than the EC tree, and the OKP methods combined were as close. In ecModels, values combined with predictions set high-turnover enzymes such as ATP synthase too low. The default therefore uses predictions where measurements give no value. +## Provenance of a kcat + +`ec.source` records where the kcat of each reaction came from. An entry has the form `[ ()][ | tuned=[+...] (prior=)]`: + +| Entry | Meaning | +| --- | --- | +| `brenda (wc=0, origin=1)` | a BRENDA match, with the number of EC levels that were wildcarded (`wc`) and the organism closeness of the match (`origin`) | +| `combined (sd=0.61, n=6)` | the combination of `n` sources, with the uncertainty `sd` in log10 units | +| `custom`, `standard`, `isozymes` | a curated kcat, the standard kcat, and the mean over the isozymes of the reaction | +| `manual` | a kcat that `setKcatForReactions` (Python `set_kcat_for_reactions`) set | +| `brenda (wc=0, origin=2) \| tuned=cmaes (prior=6.55)` | a kcat that tuning changed, with the kcat before the first tuning as `prior` | + +The origin is the label of the kcat source in lower case with underscores (`brenda`, `ec_tree`, `okp_catapro`). The detail has the pairs `wc` and `origin` for a BRENDA match and `sd` and `n` for a combined value. The assignment writes a new origin and drops a tuning status. `sensitivityTuning` and `cmaesKcatTuning` (Python `sensitivity_tuning` and `cmaes_kcat_tuning`) keep the origin and detail of every kcat they change and add their method, `sensitivity` or `cmaes`, to the tuning status. The `prior` stays the kcat before the first tuning, and a second tuning with the same method adds nothing. + +`parseKcatSource` and `formatKcatSource` read and write these entries. The parser returns the origin as it was written, the detail pairs (a number when the value is a plain decimal number, text otherwise), the tuning methods and the prior. An entry that does not follow the form is read as one origin without detail, so an entry that an earlier release wrote stays readable. The formatter writes the origin in lower case with underscores, a number with six significant digits and a prior only together with a tuning status. A detail pair without a value, with an infinite value or with a key that does not start with a letter is left out. An empty origin with a detail or a tuning status is written as `unknown`. + +::::{tab-set} +:::{tab-item} Ⓜ️ MATLAB +:sync: matlab + +```matlab +info = parseKcatSource('brenda (wc=0, origin=2) | tuned=cmaes (prior=6.55)'); +info.origin % 'brenda' +info.detail % struct with wc = 0 and origin = 2 +info.tuned % {'cmaes'} +info.prior % 6.55 +text = formatKcatSource('brenda', struct('wc', 0, 'origin', 2), {'cmaes'}, 6.55); +``` +::: +:::{tab-item} 🐍 Python +:sync: python + +```python +from geckopy import format_kcat_source, parse_kcat_source + +info = parse_kcat_source("brenda (wc=0, origin=2) | tuned=cmaes (prior=6.55)") +info.origin # 'brenda' +info.detail # {'wc': 0.0, 'origin': 2.0} +info.tuned # ('cmaes',) +info.prior # 6.55 +text = format_kcat_source("brenda", {"wc": 0, "origin": 2}, ["cmaes"], 6.55) +``` +::: +:::: + +Functions that read `ec.source` use the origin. `getStandardKcat` and `removeStandardKcat` (Python `assign_standard_kcat` and `remove_standard_kcat`) treat a row as the standard kcat when its origin is `standard` and it has no tuning status, so a standard kcat that tuning changed is kept. The trust tiers of evotune group the kcats by the origin. + ## Run the assignment ::::{tab-set} diff --git a/docs/guide/applying-kcats.md b/docs/guide/applying-kcats.md index f6fcf9b..b84c393 100644 --- a/docs/guide/applying-kcats.md +++ b/docs/guide/applying-kcats.md @@ -134,7 +134,7 @@ The same overwrite behaviour and the same gene-match threshold of 50 % apply her ## Assign kcats from the source files -`assignKcats` determines one kcat per reaction from the kcat source files, writes `ec.kcat` and `ec.source`, and applies the kcat constraints with `applyKcatConstraints`. The order of the sources follows the preset or the stages of `[kcat_assignment]`; [Kcat assignment](../gecko4-kcat-assignment.md) describes the presets, the stages and the gathering of missing source files with `updateKcatSources`. Kcats that the model had are replaced, because the source files are the input of the assignment. After the stages, `assignKcats` fills reactions without a kcat from their isozymes for full ecModels when `isozymes` is true, and gives the remaining reactions the standard kcat when `standard` is true; both options are true by default. +`assignKcats` determines one kcat per reaction from the kcat source files, writes `ec.kcat` and `ec.source` (see [Provenance of a kcat](../gecko4-kcat-assignment.md#provenance-of-a-kcat)), and applies the kcat constraints with `applyKcatConstraints`. The order of the sources follows the preset or the stages of `[kcat_assignment]`; [Kcat assignment](../gecko4-kcat-assignment.md) describes the presets, the stages and the gathering of missing source files with `updateKcatSources`. Kcats that the model had are replaced, because the source files are the input of the assignment. After the stages, `assignKcats` fills reactions without a kcat from their isozymes for full ecModels when `isozymes` is true, and gives the remaining reactions the standard kcat when `standard` is true; both options are true by default. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB @@ -223,7 +223,7 @@ This step does not apply to light ecModels, where the most efficient isozyme set Reactions without genes associated in the starting GEM (empty gene-reaction rules) cannot get enzyme constraints, for lack of enzyme data. For such reactions, excluding exchange, spontaneous, transport and pseudo-reactions (reaction names that contain `pseudoreaction` or `SLIME rxn`, and the reactions in `data/pseudoRxns.tsv`), a standard kcat and a standard pseudo-enzyme (`prot_standard`) constrain catalytic capacity instead. The standard kcat is the median of the kcat values of the reactions in the same subsystem, when the subsystem has at least 10 reactions with a kcat (the option `threshold`), and the median of every kcat in `ec.kcat` otherwise. The standard molecular weight is the median across every protein in the organism, and a `usage_prot_standard` reaction is added. -Reactions that are annotated with an enzyme but have a kcat of 0 or `NaN` receive the standard kcat as well and keep their enzyme. Earlier standard assignments (`standard` in `ec.source`) are removed when the function runs again. +Reactions that are annotated with an enzyme but have a kcat of 0 or `NaN` receive the standard kcat as well and keep their enzyme. Earlier standard assignments (an `ec.source` with the origin `standard` and no tuning status) are removed when the function runs again, and a standard kcat that tuning has changed is kept. ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB diff --git a/docs/guide/growth-rate-tuning.md b/docs/guide/growth-rate-tuning.md index bf3a951..7d563ca 100644 --- a/docs/guide/growth-rate-tuning.md +++ b/docs/guide/growth-rate-tuning.md @@ -383,7 +383,7 @@ MATLAB accepts the options as name-value pairs (`sensitivityTuning(ecModel, 'fol Both toolboxes also provide a CMA-ES-based kcat tuning (`cmaesKcatTuning` in MATLAB, `cmaes_kcat_tuning` in Python), described in [Tuning against experimental data](tuning-against-experimental-data.md). -`tunedKcats` (Python `tuning_result`) documents which kcat values were changed, with their previous value, source and the catalysed reaction. It is inspected to check whether a changed value was gathered incorrectly from a kcat source. In a full ecModel, `ec.source` of a tuned reaction reads `sensitivityTuning`, and `ec.notes` holds the kcat before the tuning and its source (`preTuneKcat= | source:`). A reaction that an earlier run has tuned keeps the notes of that run. In a light ecModel, `ec.source` and `ec.notes` are not changed. Python `TunedKcatsResult.corrections()` returns the changes as the list of corrections that [Tuning against experimental data](tuning-against-experimental-data.md#read-the-result) describes. +`tunedKcats` (Python `tuning_result`) documents which kcat values were changed, with their previous value, source and the catalysed reaction. It is inspected to check whether a changed value was gathered incorrectly from a kcat source. `ec.source` of a tuned reaction keeps its origin and detail and gains the tuning status, for example `brenda (wc=0, origin=1) | tuned=sensitivity (prior=0.05)`, where the prior is the kcat before the first tuning (see [Provenance of a kcat](../gecko4-kcat-assignment.md#provenance-of-a-kcat)). A reaction that an earlier run has tuned keeps the prior of that run and adds no second `sensitivity`. A source that is empty is written as `unknown`. `ec.notes` is not changed. In a light ecModel the status is added to every ec row of the tuned reaction. Python `TunedKcatsResult.corrections()` returns the changes as the list of corrections that [Tuning against experimental data](tuning-against-experimental-data.md#read-the-result) describes. :::{admonition} Many kcat values are changed during tuning :class: note @@ -472,7 +472,7 @@ print(conv_kcat) ::: :::: -The converted kcat is 5.3358, rounded to 5.34. The value in the ecModel is replaced with the new literature value, either documented in `data/kcats/custom.tsv` (see [Applying kcats](applying-kcats.md#provide-custom-kcat-values)) or applied directly. `setKcatForReactions` (Python `set_kcat_for_reactions`) sets `ec.kcat` and `ec.source` (`setKcatForReactions`) of the reaction, and `applyKcatConstraints` (Python `apply_kcat_constraints`) transfers the new value to the stoichiometric matrix: +The converted kcat is 5.3358, rounded to 5.34. The value in the ecModel is replaced with the new literature value, either documented in `data/kcats/custom.tsv` (see [Applying kcats](applying-kcats.md#provide-custom-kcat-values)) or applied directly. `setKcatForReactions` (Python `set_kcat_for_reactions`) sets `ec.kcat` of the reaction and `ec.source` to `manual`, and `applyKcatConstraints` (Python `apply_kcat_constraints`) transfers the new value to the stoichiometric matrix: ::::{tab-set} :::{tab-item} Ⓜ️ MATLAB diff --git a/docs/guide/model-adapter-parameters.md b/docs/guide/model-adapter-parameters.md index 20ed2aa..3dd6c9c 100644 --- a/docs/guide/model-adapter-parameters.md +++ b/docs/guide/model-adapter-parameters.md @@ -124,7 +124,7 @@ The `[evotune]` section holds the hyperparameters of the CMA-ES kcat tuning desc | TOML key | MATLAB parameter | Default | Description | |---|---|---|---| | `evotune.sigma0_log_default` | `evotune.sigma0logDefault` | `0.5` | Prior standard deviation (log) of the kcats whose source is in no group | -| `evotune.source_groups` | `evotune.kcatSources` | none | Trust tiers: a table `[evotune.source_groups.]` per group with the `ec.source` values it covers as `sources`. With `match_okp = true`, a group also covers the method of `[okp] method` | +| `evotune.source_groups` | `evotune.kcatSources` | none | Trust tiers: a table `[evotune.source_groups.]` per group with the origins of `ec.source` it covers as `sources`. With `match_okp = true`, a group also covers the method of `[okp] method` | | `evotune.sigma0_log_source` | `evotune.sigma0logSource` | none | Prior standard deviation (log) per group; the keys are the group names of `evotune.source_groups` | | `evotune.rmse_threshold` | `evotune.rmseThreshold` | `0.2` | The search stops when the best RMSE reaches this value | | `evotune.max_generations` | `evotune.maxGenerations` | `150` | Maximum number of CMA-ES generations | diff --git a/docs/guide/tuning-against-experimental-data.md b/docs/guide/tuning-against-experimental-data.md index 63cd176..4b53e5e 100644 --- a/docs/guide/tuning-against-experimental-data.md +++ b/docs/guide/tuning-against-experimental-data.md @@ -118,7 +118,7 @@ custom = 0.1 The default template sets `sigma0_log_default = 0.5`, the groups `dlkcat`, `brenda` and `custom` with `sigma0_log_source` values 0.4, 0.2 and 0.1, `max_growth_weight = 1.0`, `prior_penalty_weight = 0.03`, `tie_isozymes = true`, `rmse_threshold = 0.2` and `max_generations = 150`. MATLAB reads the same keys under other names, for example `evotune.sigma0logDefault`, listed in `adapterParameters.tsv`. -- **Trust tiers** (`source_groups`, `sigma0_log_source` and `sigma0_log_default`). Kcats are grouped by their entry in `ec.source`, and each group has a standard deviation in log space. A smaller value means more trust, so the search needs stronger evidence before it moves such a kcat far. With the values above, a curated kcat (`custom`, 0.1) is three times more trusted than a kcat of an unlisted source (0.3). A kcat belongs to the group that lists its `ec.source`, or the part of `ec.source` before ` (`, so `brenda (wc=0, origin=1)` is in the group that lists `brenda` and `combined (sd=0.10, n=2)` in the group that lists `combined`. Entries of `sources` are matched case-insensitively, against the whole label and against the part before ` (`. A group with `match_okp = true` also takes the kcats whose `ec.source` equals the configured OpenKineticsPredictor method (`CataPro` in the example, one of the methods named in the template), matched in the same way. When a label matches several groups, the first matching group applies in Python and the last matching group in MATLAB. A kcat in no group takes `sigma0_log_default`. The tiers depend on the source labels of the model, so no tier set applies to every model. +- **Trust tiers** (`source_groups`, `sigma0_log_source` and `sigma0_log_default`). Kcats are grouped by the origin of their `ec.source`, and each group has a standard deviation in log space. A smaller value means more trust, so the search needs stronger evidence before it moves such a kcat far. With the values above, a curated kcat (`custom`, 0.1) is three times more trusted than a kcat of an unlisted source (0.3). A kcat belongs to the group that lists the origin of its `ec.source` (the text before the detail and the tuning status), so `brenda (wc=0, origin=1)` is in the group that lists `brenda` and `combined (sd=0.10, n=2) | tuned=cmaes (prior=2)` in the group that lists `combined`. Entries of `sources` are matched case-insensitively, against the origin and against the whole `ec.source`. A group with `match_okp = true` also takes the kcats whose `ec.source` equals the configured OpenKineticsPredictor method (`CataPro` in the example, one of the methods named in the template), matched in the same way. When a label matches several groups, the first matching group applies in Python and the last matching group in MATLAB. A kcat in no group takes `sigma0_log_default`. The tiers depend on the source labels of the model, so no tier set applies to every model. - **`max_growth_weight`**. The combined score is `(rmse_flux + w * rmse_max_growth) / (w + 1)`. At `2`, the growth-rate error counts double against the flux error, which suits growth rates measured on many carbon sources and fluxes measured mainly on one. - **`prior_penalty_weight`**. Adds `w * mean(((log k - log k0) / sigma0)^2)` to the score, a charge for moving a kcat that is scaled by the trust in its prior. Without the term the fit is flat along many directions: several different kcat vectors fit equally well, and the search returns an arbitrary point that does not reproduce with another seed. The default of `0.03` keeps large corrections in the same direction and within a few fold of each other across seeds, at a small cost in fit. A value of `0` scores on the fit alone. The suitable strength depends on the model and the data, since it scales with `sigma0_log` and with the objective. `tunePriorPenaltyWeight` (Python `tune_prior_penalty_weight`) runs `cmaesKcatTuning` for each of `candidates` (default `0`, `0.01`, `0.03`, `0.1`) at each of `seeds` (default `0` and `1`) and reports the fit cost against the reproducibility across seeds. It costs one full tuning run per candidate and seed, which makes it an occasional calibration. - **`tie_isozymes`**. Several ecModel reactions are one enzymatic reaction split over isozyme copies. When copies share a prior value and a source, no condition can distinguish them, so an untied search can assign them a difference without biological meaning. Tying gives such copies one shared kcat. @@ -252,6 +252,8 @@ Growth that needs special handling for the organism, such as forced anaerobic co - `rmse_trace`, `objective_trace` (MATLAB `rmseTrace`, `objectiveTrace`): the best plain-fit RMSE so far and the best optimised objective so far, per generation. They are identical when `prior_penalty_weight` is 0. A trace that is flat for many generations before the end indicates a stalled run. - `new_kcat`, `old_kcat`, `rxns`, `groups` (MATLAB `newKcat`, `oldKcat`, `rxns`, `groups`): the tuned and prior kcats of the searched set as parallel arrays, with the trust tier of each kcat. Tied isozyme copies share one value in `new_kcat`. - `converged`: whether `rmse_threshold` was reached before `max_generations`. + +The tuned model has the tuning status `tuned=cmaes` in `ec.source` of every kcat that changed, with the kcat before the first tuning as `prior` (see [Provenance of a kcat](../gecko4-kcat-assignment.md#provenance-of-a-kcat)). - `n_generations` (MATLAB `nGenerations`): the number of generations that ran. The final RMSE alone does not show whether a tuned kcat can be trusted: @@ -292,7 +294,7 @@ open("corrections.tsv", "w").write(corrections_tsv(rows)) | Error that `evotune_data` has neither `flux_data` nor `max_grate` | Neither `evotuneFluxData.tsv` nor `evotuneMaxGrowth.tsv` is in `/data/` | Add one of the files, or pass the loaded data | | Error `No tunable kcats` | `ec.kcat` is not positive anywhere, or `tunableMask` excludes every kcat with a value | Assign kcats first, or widen the mask | | Error `Only 1 free parameter(s) after masking and tying` | The mask and `tie_isozymes` leave fewer than two free parameters | Widen `tunableMask` or raise `targetImpactShare` | -| Most kcats take `sigma0_log_default` | The labels in `source_groups` do not match the `ec.source` entries of the model | List the labels that occur in `ec.source` (for example `ec_tree`, `combined` or `custom`) in `source_groups` | +| Most kcats take `sigma0_log_default` | The labels in `source_groups` do not match the origins of `ec.source` in the model | List the origins that occur in `ec.source` (for example `ec_tree`, `combined` or `custom`) in `source_groups` | | Large corrections differ in direction between seeds | The fit is flat along these kcats | Raise `prior_penalty_weight`, calibrated with `tunePriorPenaltyWeight` | ## See also