Tune kcats against experimental data#
The advanced kcat tuning fits many kcats at once to maximum growth rates and exchange fluxes, measured in one or more conditions, by minimising the root-mean-square error (RMSE) between simulated and measured values. It searches with CMA-ES (covariance matrix adaptation evolution strategy), and the trust in the source of each kcat limits how far the kcat moves. The steps are: prepare the data files, configure the tuning, rank the kcats by their effect on the fit, review the assignment of the top kcats, and tune. The result is an ecModel whose selected kcats fit the data, and a list of the changed kcats. Choose a kcat tuning compares this tuning with the standard tuning.
Place in the workflow
The diagram orders the functions of this page within the workflow. Boxes with a dashed outline are optional steps, a dotted arrow is an optional path, and a diamond is a choice. Rounded boxes with a dotted outline are the context, other pages or the model to start from, and a click on one opens its page.
---
config:
flowchart:
useMaxWidth: false
---
flowchart TB
classDef opt stroke-dasharray: 5 4
classDef ctx fill:transparent,stroke-dasharray: 2 3
PV(["Previous: Choose a kcat tuning"]):::ctx
DF["prepare the data files<br/>(read by loadEvotuneData, which the tuning calls)"]
CG["[evotune] in model_adapter.toml"]
SC["screenKcatLeverage"]
RV["reviewKcatAssignment<br/>ecStatsFromBrenda"]:::opt
TP["tunePriorPenaltyWeight<br/>seeds and reproducibility"]:::opt
CM["cmaesKcatTuning<br/>selectTunableMask on the screen"]
PV --> DF --> CG --> SC --> CM
SC -.-> RV -.-> CM
SC -.-> TP -.-> CM
NP(["Next: Constrain enzymes with proteomics (optional)"]):::ctx
NA(["Next: Analyse an ecModel"]):::ctx
CM --> NP
CM --> NA
click PV href "kcat-tuning.html"
click NP href "proteomics.html"
click NA href "analysis.html"
---
config:
flowchart:
useMaxWidth: false
---
flowchart TB
classDef opt stroke-dasharray: 5 4
classDef ctx fill:transparent,stroke-dasharray: 2 3
PV(["Previous: Choose a kcat tuning"]):::ctx
DF["prepare the data files<br/>(read by load_evotune_data, which the tuning calls)"]
CG["[evotune] in model_adapter.toml"]
SC["screen_kcat_leverage"]
RV["review_assignment<br/>ec_stats_from_brenda"]:::opt
TP["tune_prior_penalty_weight<br/>seeds and reproducibility"]:::opt
CM["cmaes_kcat_tuning<br/>select_tunable_mask on the screen"]
PV --> DF --> CG --> SC --> CM
SC -.-> RV -.-> CM
SC -.-> TP -.-> CM
NP(["Next: Constrain enzymes with proteomics (optional)"]):::ctx
NA(["Next: Analyse an ecModel"]):::ctx
CM --> NP
CM --> NA
click PV href "kcat-tuning.html"
click NP href "proteomics.html"
click NA href "analysis.html"
Functions#
MATLAB |
Python |
Note |
|---|---|---|
reads the three data files; the tuning functions call it when no data are given |
||
ranks the kcats by their effect on the fit, without tuning |
||
selects the top kcats of the screen for the search |
||
flags kcat assignments that may be wrong, independent of the data |
||
summarises the BRENDA data per EC number for the review |
||
searches the selected kcats for the best fit to the data |
||
runs the tuning for several |
Setup#
An ecModel with assigned kcats (see Choose the kcat sources) and a set protein pool (see Set the protein pool), in a project with
model_adapter.toml.At least one of the files
evotuneMaxGrowth.tsvandevotuneFluxData.tsvin thedatafolder of the project. The tutorialfull_ecModelof GECKO has all three data files in itsdatafolder.MATLAB:
nProcabove 1 needs the Parallel Computing Toolbox.cmaesKcatTuninghas its own CMA-ES. Python: geckopy installs the CMA-ES packagecma.
Prepare the data files#
loadEvotuneData reads three tab-separated files from <project>/data/. A missing file is skipped.
File |
Contents |
|---|---|
|
maximum growth rates, one row per condition |
|
growth rates and exchange fluxes, one row per condition |
|
reactions that carry no flux in any condition of |
The first two files have the layout of the flux data file that loadFluxData reads:
Condition Ptot grRate glucose (r_1714) fructose (r_1709) oxygen (r_1992) ethanol (r_1761) evotuneRMSEweight source
glucose NaN 0.41 -1000 NaN NaN NaN 1 reference
fructose NaN 0.338 NaN -1000 NaN NaN 1 reference
Column |
Meaning |
|---|---|
1 ( |
the carbon source of the row. It must equal the metabolite name of one exchange column, for example |
2 ( |
total protein content in g/gDCW, or |
3 ( |
measured growth rate in 1/h |
|
measured exchange flux in mmol/gDCW/h, or |
|
optional; the RMSE of the row is multiplied by this weight |
|
optional; free text, not used in the fit |
Each row is simulated with the uptake of its own carbon source open and the uptake of the carbon sources of the other rows of the same file closed (lower bound 0):
In
evotuneMaxGrowth.tsv, the uptake of the carbon source of the row is set to -1000, and the growth rate is the sole compared value. The value in the carbon source column is not read.In
evotuneFluxData.tsv, the lower bound of the carbon source uptake is set to the measured value. The growth rate and every exchange flux that is notNaNare compared, and so is every reaction ofevotuneZeroExch.tsvthat carries flux in the simulation.
Fluxes are compared in carbon units: each flux is multiplied by the number of carbon atoms of the exchanged metabolite (1 for a metabolite without carbon), and the growth rate by 41 Cmmol/gDCW. A row whose simulation is infeasible has an RMSE of 99. The RMSE of a file is the mean over its rows, and the RMSE of the fit is (rmse_flux + w * rmse_max_growth) / (w + 1), with w the setting max_growth_weight.
evotuneZeroExch.tsv has the header Rxns and one reaction ID per line.
Configure the tuning#
The settings are in the [evotune] table of model_adapter.toml. Every setting has a default (see Model adapter parameters). The template of createGECKOproject writes these values:
[evotune]
sigma0_log_default = 0.5
max_growth_weight = 1.0
prior_penalty_weight = 0.03
tie_isozymes = true
rmse_threshold = 0.2
max_generations = 150
[evotune.source_groups.dlkcat]
sources = ["dlkcat"]
[evotune.source_groups.brenda]
sources = ["brenda"]
[evotune.source_groups.custom]
sources = ["custom"]
[evotune.sigma0_log_source]
dlkcat = 0.4
brenda = 0.2
custom = 0.1
Setting (MATLAB field) |
Meaning |
|---|---|
|
trust groups, each with the |
|
standard deviation in log space for each group; the keys are the group names |
|
standard deviation for a kcat whose source is in no group |
|
weight |
|
weight |
|
isozyme copies of one reaction with the same kcat and the same group get one shared kcat |
|
the search stops when the best RMSE reaches this value; a negative value never stops the search early |
|
maximum number of CMA-ES generations |
A smaller sigma0_log is more trust: the search moves such a kcat less, and the screen ranks it lower. A kcat belongs to a group when the origin of its ec.source, or the whole ec.source, equals one of the sources of the group, without regard to case (see Provenance of a kcat). brenda (wc=0, origin=1) is in the group that lists brenda, combined (sd=0.10, n=2) in the group that lists combined, and a tuned kcat such as brenda (wc=0, origin=1) | tuned=cmaes (prior=2) stays in the group of brenda. With match_okp = true, a group also covers the method of [okp] method.
The groups depend on the origins in the model. With the default kcat assignment, ec.source also holds origins such as ec_tree, combined and standard, which the template groups do not list, so these kcats take sigma0_log_default. List the origins of ec.source (parseKcatSource, Python parse_kcat_source, returns the origin of each entry) and add a group for each origin that needs its own trust. MATLAB reads source_groups as a flat list of source labels (kcatSources) with one width per label (sigma0logSource), so in MATLAB the group of a kcat, in screen.sourceGroup and result.groups, is the matched source label; in Python it is the group name. When a label matches several groups, the first group applies.
Rank the kcats by their effect#
screenKcatLeverage multiplies and divides each kcat (or each group of tied isozyme copies) by fold (default 2) and records the largest change of the RMSE, the leverage. The rows are sorted by leverage multiplied by the sigma0_log of the kcat. The screen runs one simulation per condition for each of these probes and one baseline, so on a genome-scale model it takes about as long as a tuning run.
ModelAdapterManager.setDefault('path/to/project');
ecModel = loadEcModel();
screen = screenKcatLeverage(ecModel, 'nProc', 8);
removevars(screen(1:20, :), 'positions')
from geckopy import ModelAdapter, load_ec_model
from geckopy.kcat_tuning.evotune import screen_kcat_leverage
adapter = ModelAdapter.from_folder("path/to/project")
ec_model = load_ec_model(adapter=adapter) # models/ecModel.yml
screen = screen_kcat_leverage(ec_model, n_proc=8)
screen.drop(columns="_positions").head(20)
The screen has one row per kcat or tied group: rxnId (Python rxn_id), nIsozymes (n_isozymes), sourceGroup (source_group), kcat0, leverage, sigma0log (sigma0_log), rank (leverage times sigma0log) and cumLeverageShare (cum_leverage_share), the sum of rank from the first row to this row as a fraction of the total. The column positions (Python _positions) holds the indices into ec.rxns of each row. The screen scores two kcat vectors for each kcat or tied group, so its time grows with the number of kcats screened; tunableMask (Python tunable_mask) restricts the screen to a subset.
Review the assignments of the top kcats#
reviewKcatAssignment checks each kcat for these problems: an EC number with specific-activity rows but no kcat rows in BRENDA (no-ec-evidence; an EC number that is not in BRENDA is not flagged), the same value in 5 or more reactions (repeated-value), the maximum of an EC number that is more than 3 times its median (ec-maximum), a value outside 0.01 to 10000 per s (magnitude), and a custom value that equals a BRENDA value of its EC number (custom-duplicate). The checks that need BRENDA statistics are skipped without ecStats. With the leverage of the screen the findings are sorted by leverage, and coverage or top shortens the list. Correct a wrong kcat in its source (see Choose the kcat sources and Set custom kcats); every model built from the same files then has the correction.
[KCATcell, SAcell] = loadBRENDAdata('kcatAggregation', 'max');
KCATmedianCell = loadBRENDAdata('kcatAggregation', 'median');
ecStats = ecStatsFromBrenda(KCATcell, SAcell, KCATmedianCell);
leverage = zeros(numel(ecModel.ec.rxns), 1);
for i = 1:height(screen)
leverage(screen.positions{i}) = screen.leverage(i);
end
findings = reviewKcatAssignment(ecModel.ec.rxns, ecModel.ec.kcat, ...
ecModel.ec.source, ecModel.ec.eccodes, 'ecStats', ecStats, ...
'leverage', leverage, 'coverage', 0.9);
writetable(findings, 'findings.tsv', 'FileType', 'text', 'Delimiter', '\t')
import numpy as np
from geckopy import ec_stats_from_brenda, load_brenda_data, review_assignment
from geckopy.gather_kcats.review import findings_tsv
ec_stats = ec_stats_from_brenda(load_brenda_data(adapter.get_brenda_db_folder()))
leverage = np.zeros(len(ec_model.ec.rxns))
for _, row in screen.iterrows():
leverage[list(row["_positions"])] = row["leverage"]
findings = review_assignment(
ec_model.ec.rxns, ec_model.ec.kcat, ec_model.ec.source, ec_model.ec.eccodes,
ec_stats=ec_stats, leverage=leverage, coverage=0.9,
)
open("findings.tsv", "w").write(findings_tsv(findings))
Each finding has the reaction, its EC number, source, kcat and leverage, the number of isozyme copies, the number of other reactions that share an enzyme (with the option enzymes), the names of the checks and a detail in words. Tied isozyme copies are reported once. Kcats with the source standard are reported when include lists standard-fallback, and the check tied-isozymes is added when include lists it; the default include is empty.
Run the advanced tuning#
cmaesKcatTuning uses selectTunableMask to select the kcats to search: the top rows of the screen, up to the first row at which cumLeverageShare reaches targetImpactShare (default 0.9). With screen the function uses that screen; without it, the function runs a new screen. tunableMask (Python tunable_mask) gives the set of kcats directly and takes precedence over screen.
[ecModel, result] = cmaesKcatTuning(ecModel, 'screen', screen, ...
'nProc', 8, 'seed', 0);
saveEcModel(ecModel, 'ecModel_tuned.yml');
from geckopy import save_ec_model
from geckopy.kcat_tuning.evotune import cmaes_kcat_tuning
result = cmaes_kcat_tuning(ec_model, screen=screen, n_proc=8, seed=0)
save_ec_model(ec_model, "ecModel_tuned.yml", adapter=adapter)
Each candidate kcat lies between min(0.01, k0/100) and max(10000, 100*k0) per s, where k0 is the kcat before tuning. After the run, the selected kcats hold the values of the best candidate, and their enzyme constraints are applied. Python changes ec_model in place. popsize sets the number of candidates per generation (default 4 + floor(3*log(n)) for n free kcats). In Python, the search can also stop earlier on a convergence criterion of the cma package, such as tolx.
Conditions that change the model#
A data row with oxygen uptake 0 or with a value of Ptot needs a function that changes the model. MATLAB runs the functions named by make_model_anaerobic and change_protein_biomass in the [matlab] table of model_adapter.toml (see Model adapter parameters). Python takes these functions through the arguments make_anaerobic(model) and change_protein_biomass(model, ptot); tutorials/full_ecModel/code/anaerobic.py in the geckopy repository has an example. Without a function, the condition is simulated without the change.
Seeds, reproducibility and parallel runs#
seed makes a run reproducible. MATLAB and Python have different CMA-ES implementations, so the same seed gives different results in the two toolboxes. In Python, a run with n_proc above 1 gives the same result as a run with n_proc=1 and the same seed. nProc has the default 1 in MATLAB; n_proc has the default cobra.Configuration().processes in Python.
Different kcat vectors can fit the data equally well, so two seeds can move a kcat in different directions. Run the tuning with a second seed and compare the large changes (above two-fold): they should be in the same direction and of similar size. If they are not, increase prior_penalty_weight. tunePriorPenaltyWeight (Python tune_prior_penalty_weight) runs the tuning for each value of candidates (default 0, 0.01, 0.03 and 0.1) and each of seeds (default 0 and 1), on the same set of kcats, and reports per value the fit, the number of changed kcats and the agreement between seeds. It costs one tuning run per value and seed, and the model is not changed.
Read the result#
result (Python EvotuneResult) has these fields:
MATLAB |
Python |
Meaning |
|---|---|---|
|
|
the selected kcats before and after tuning, and the trust group of each; tied copies share one value |
|
|
the best RMSE and the best value of the minimised objective, per generation; the two are equal when |
|
|
number of generations that ran |
|
|
whether the best RMSE reached |
ec.source of every kcat that changed gets the tuning status tuned=cmaes, with the kcat before the first tuning as prior (see Provenance of a kcat). nChanged (Python n_changed) counts the kcats that differ from their value before tuning by more than 2 %. parsimonyFrontier (Python parsimony_frontier) sets each kcat that moved less than a threshold, in units of its sigma0_log, back to the value before tuning, and scores the result for a series of thresholds with a scoring function that the caller gives. bestParsimonious (Python best_parsimonious) returns the point with the fewest changed kcats whose RMSE is within 2 % of the best RMSE. In Python, result.corrections(leverage=...) returns one row per changed kcat, sorted by the leverage of the screen; leverage has one value per entry of result.rxns; corrections_tsv in geckopy.kcat_tuning writes the rows as TSV. Check the tuned model against data that were not used in the fit: an improvement on the fitted conditions without an improvement on other data indicates overfitting. As with the standard tuning, check the large changes against the source of each kcat (see Choose a kcat tuning), and keep curated values in data/kcats/custom.tsv.
Troubleshooting#
Problem |
Possible reason |
Solution |
|---|---|---|
Error |
Neither |
Add one of the files |
Error that a carbon source cannot be matched by name with an exchange reaction |
The |
Use the metabolite name of the column header as the condition |
Error |
No kcat is above 0, or the mask excludes every kcat |
Assign kcats first, or widen the mask |
Error |
The mask and the isozyme tying leave fewer than two free kcats |
Raise |
Error that the keys of |
A group has no width, or a width has no group |
Give each group one value in |
Most kcats take |
The |
List the origins that occur in |
The large changes differ in direction between seeds |
Several kcat vectors fit the data equally well |
Increase |
See also#
Choose a kcat tuning, the standard tuning and the check of a tuned kcat.
Files in the data folder, every file of the
datafolder.Model adapter parameters, the
[evotune]settings in both toolboxes.API reference, every function in both toolboxes.