Model adapter parameters#
model_adapter.toml in the project folder holds the parameters of a GECKO 4 project. GECKO (MATLAB) and geckopy (Python) read the same file. The section overview is in Project format 4. The tables give the parameters, their defaults and the MATLAB name of each parameter. The defaults are those of src/model_adapter/adapterParameters.tsv of GECKO, which geckopy uses as well.
Reading the file#
Paths in the file are relative to the project folder. A key that is left out gets the default of the tables. The project folder is the folder of the file, so path is no key.
Both toolboxes check every key when they read the file. A key that the tables do not list is an error, and so is a key inside a table that the table does not take: under [evotune.source_groups.<group>], in a [[kcat_assignment.stage]] entry and under [kcat_sources.<name>]. The message names the file and the key with its full path:
<full path of model_adapter.toml>: unknown key kcat_sources.brenda.k in model_adapter.toml
GECKO raises the error with the identifier GECKO:loadAdapterParams, and ModelAdapter.from_folder of geckopy raises ValueError. A parameter that GECKO alone uses goes under [matlab.params].
ModelAdapterManager.setDefault(projectPath);
from geckopy import ModelAdapter
adapter = ModelAdapter.from_folder(project_path)
ModelAdapterManager.setDefault makes the adapter the default of all GECKO functions that take the option modelAdapter. In geckopy, adapter.params holds the parameters under the TOML key names, and an ecModel made with make_ec_model holds the adapter as ec_model.adapter.
The full_ecModel tutorial uses these entries:
conv_gem = "models/yeast-GEM.yml"
org_name = "saccharomyces cerevisiae"
sigma = 0.5
p_tot = 0.5
f = 0.5
gr_exp = 0.41
c_source = "r_1714"
bio_rxn = "r_4041"
enzyme_comp = "cytoplasm"
[kegg]
id = "sce"
gene_id = "kegg"
[uniprot]
type = "proteome"
id = "UP000002311"
gene_id_field = "gene_oln"
reviewed = true
[complex]
taxonomic_id = 559292
[spontaneous]
name_contains = "spontaneous"
Showing the resolved parameters#
showAdapterParams (GECKO) and geckopy adapter show (geckopy) print the value of every parameter and the origin of the value. Both print the same lines.
showAdapterParams(ModelAdapterManager.getDefault())
T = showAdapterParams(adapter); % table with the columns key, value and origin
geckopy adapter show path/to/project
from geckopy import ModelAdapter, show_adapter_params
show_adapter_params(ModelAdapter.from_folder(project_path))
Each line has the form <key> = <value> [<origin>], in the order of adapterParameters.tsv. The origin is file (set in model_adapter.toml, or by an adapter class), default, preset <name> (set by the kcat assignment preset) or not set. Strings are printed without quotes, lists comma-separated, and whole numbers without decimals. The kcat assignment stages, the settings of each kcat source and the evotune source groups are printed as they are resolved. Some of the lines for a project that sets gr_exp and no kcat assignment:
sigma = 0.5 [default]
gr_exp = 0.41 [file]
complex.taxonomic_id = [not set]
evotune.source_groups.custom = custom; sigma0_log 0.1 [default]
evotune.max_growth_weight = 1 [default]
kcat_assignment.preset = brenda_ec_tree [default]
kcat_assignment.stage[1] = select: custom, database_top, ec_tree; top_origin_limit=1 [preset brenda_ec_tree]
kcat_assignment.stage[2] = combine: okp [preset brenda_ec_tree]
kcat_sources.brenda.aggregation = median [preset brenda_ec_tree]
kcat_sources.ec_tree.k = 5 [preset brenda_ec_tree]
kcat_sources.okp.method = KinForm-H [default]
A stage line lists the action, the sources, and the criteria and limits that differ from the defaults. With stages in the file, the preset line is kcat_assignment.preset = none (stages are given) [file].
Model and protein pool#
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
none |
Layout version of the project folder. |
|
|
none (required in geckopy) |
Path to the starting conventional GEM file, for example |
|
|
none (required in geckopy) |
Scientific name of the organism, used by |
|
|
|
Average enzyme saturation factor |
|
|
|
Total protein content in the cell [g protein/gDW] |
|
|
|
Fraction of enzymes in the ecModel relative to all proteins (g enzyme/g protein). |
|
|
none |
Growth rate in h^-1 that the model should reach when the nutrient uptake does not limit it, for example the measured maximum growth rate. See below the table |
|
|
|
Identifier of the exchange reaction of glucose or of another preferred carbon source |
|
|
|
Identifier of the biomass or growth pseudoreaction, whose flux is the growth rate in h^-1 |
|
|
|
Name of the compartment of the added protein pseudometabolites; must match one of the compartment names of the ecModel |
sensitivityTuning, sigmaFitter, flexibilizeEnzConcs and relaxEnzConcs (Python: sensitivity_tuning, fit_sigma, flexibilize_enz_concs and relax_enz_concs) use gr_exp as the target growth rate when the call gives none. When the call gives none and the file does not set gr_exp, they raise the error gr_exp is not set in model_adapter.toml (GECKO identifier GECKO:grExpNotSet, Python ValueError).
Database identifiers#
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
|
Organism code in the KEGG database, from the KEGG organism list |
|
|
|
Field of the KEGG entry that matches the gene identifiers of the ecModel. |
|
|
|
Whether |
|
|
|
Identifier of the UniProt data set (by taxonomy or proteome) with complete coverage of the genes of the ecModel |
|
|
|
UniProt field with the gene identifiers used in the ecModel; one of the "Returned Field" entries under "Names & Taxonomy" of the UniProt return fields |
|
|
|
Whether the data is limited to reviewed (Swiss-Prot) entries. Reviewed data has the highest confidence but can have low coverage for non-model organisms |
|
|
none |
Taxonomy identifier as available from the Complex Portal. Without it, no Complex Portal query is made |
Spontaneous reactions#
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
none |
Reactions whose name contains this text are spontaneous |
|
|
none |
TSV of spontaneous reactions, relative to the project folder: a header row, reaction identifiers in the first column and, optionally, a second column in which |
A reaction is spontaneous when either rule matches. getStandardKcat (Python: assign_standard_kcat) gives spontaneous reactions no standard kcat.
Kcat assignment#
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
|
One of |
|
|
|
Fill reactions without a kcat from their isozymes after the stages |
|
|
|
Give the remaining reactions the standard kcat |
|
|
none |
Stages in place of a preset, written as |
|
|
set by the preset |
Settings of one source file, described in Kcat source settings |
A stage has the keys action (select, the default, or combine), sources, criteria (max, min, median or mean; default max), top_origin_limit (default 4), bottom_origin_limit (default 6) and wildcard_limit (default 3). Kcat assignment describes the presets and the stages.
Kcat source settings#
A [kcat_sources.<name>] table holds the settings with which updateKcatSources (Python: update_kcat_sources) gathers the source file data/kcats/<name>.tsv. A preset sets some of these settings. A table in the file replaces the keys that it sets and keeps the other settings of the preset. Each source takes the keys in the table; Gather the source files gives their meaning and defaults.
Table |
Keys |
|---|---|
|
|
|
|
|
|
|
|
|
none |
A table of another source is an unknown key, and so is [kcat_sources.okp_<x>] unless okp_<x> is the file of an accepted OpenKineticsPredictor method (see OpenKineticsPredictor). An empty table of a known source is accepted. An entry for a known source that is not a table raises <file>: kcat_sources.<name> must be a table.
BRENDA aggregation#
kcat.tsv of the BRENDA release records a maximum and a median kcat per EC number, substrate and organism. [kcat_sources.brenda] aggregation selects which of the two is used, and no other key of the file selects it. updateKcatSources gathers brenda.tsv with this setting. kcatsFromBrenda, fuzzyKcatMatching and loadBRENDAdata (Python: kcats_from_brenda and fuzzy_kcat_matching), called without an aggregation, use the same setting as the kcat assignment configuration resolves it:
Kcat assignment in the file |
BRENDA aggregation |
|---|---|
none, so the default preset |
|
preset |
|
preset |
|
preset |
|
any, with |
the value of |
An aggregation given in the call is used in place of the setting: aggregation of kcatsFromBrenda and kcats_from_brenda, kcatAggregation of fuzzyKcatMatching and loadBRENDAdata, and aggregate of fuzzy_kcat_matching. A value other than max or median raises <file>: kcat_sources.brenda.aggregation must be max or median when the file is read, and aggregation must be max or median when it is given in a call.
To use the BRENDA maximum with the default preset:
[kcat_sources.brenda]
aggregation = "max"
Kcat tuning#
The [evotune] section holds the hyperparameters of the CMA-ES kcat tuning described in Tune kcats with evotune.
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
|
Prior standard deviation of the natural log of the kcat, for the kcats that match no source group |
|
|
four groups (see Source groups) |
Trust tiers: one table |
|
|
|
The search stops when the best RMSE reaches this value |
|
|
|
Maximum number of CMA-ES generations |
|
|
|
Weight of the maximum-growth RMSE against the flux RMSE |
|
|
|
Weight of the prior term in the search objective |
|
|
|
Give the isozyme copies of one reaction a single kcat |
Source groups#
A source group gives the kcats of some sources one prior width. Each group is a table with two required keys:
[evotune.source_groups.brenda]
sources = ["brenda"]
sigma0_log = 0.2
[evotune.source_groups.okp]
sources = ["okp_*"]
sigma0_log = 0.5
Key |
Value |
|---|---|
|
non-empty list of origins of |
|
positive number: the prior standard deviation of the natural log of the kcat. A smaller value is more trust |
The sd in an ec.source label such as combined (sd=0.10, n=2) is a standard deviation of the log10 of the kcat; a standard deviation of 0.1 in log10 is 0.23 in natural log.
A kcat is in the group of the first entry that matches it, in this order:
The entries without
*, of all groups in the order of the file. An entry matches when it equals the origin ofec.sourceor the wholeec.source, without regard to case.The patterns, the longest prefix first, and patterns of equal length in the order of the file. A pattern matches when the origin starts with its prefix, without regard to case.
A kcat is labelled with the name of its group, in sourceGroup of the screen and groups of the tuning result (Python source_group and groups). A kcat that matches no group gets sigma0_log_default. When more than 20 % of the tunable kcats match no group, the tuning warns:
<n> of <m> tunable kcats match no evotune source group and get sigma0_log_default (<value>); origins: <origins>
The warning lists up to five origins, the most frequent first and in alphabetical order among equal counts. The GECKO identifier of the warning is resolveTunableContext:unlabelled; geckopy issues a UserWarning.
Without [evotune.source_groups] in the file, the groups are:
Group |
|
|
|---|---|---|
|
|
0.1 |
|
|
0.2 |
|
|
0.3 |
|
|
0.4 |
Groups in the file replace all default groups.
OpenKineticsPredictor#
[kcat_sources.okp] method is the one setting that names the OpenKineticsPredictor (OKP) method; the default is "KinForm-H". The okp source of the presets and stages stands for the file okp_<method>.tsv of this method, updateKcatSources gathers that file, and kcatsFromOKP (Python: kcats_from_okp) called without method uses it. The [okp] table names no method; it holds the options of each request to the OKP service:
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
|
Action of OpenKineticsPredictor on sequences that are too long |
|
|
|
Return the similarity to the training data of the method |
|
|
|
Canonicalise substrate SMILES before the prediction |
[kcat_sources.okp]
method = "UniKP"
method accepts the methods that predict from one enzyme and one substrate: CataPro, CatRange, DLKcat, EITLEM, KinForm-H, KinForm-L, OmniESI, OmniESI-O2DENet and UniKP. CatPred and TurNup read whole reactions, and kcatsFromOKP does not submit them. The file of a method is okp_ followed by the method name in lower case, with each run of characters other than letters and digits replaced by _: okp_kinform_h for KinForm-H and okp_omniesi_o2denet for OmniESI-O2DENet. When the file is read, a name that is not in this list raises:
Unknown OKP method <name> in [kcat_sources.okp] method; supported: <accepted methods>
A value that is not a string raises kcat_sources.okp.method must be a string.
The API key is no parameter. It is an argument of the functions, the environment variable OKP_API_KEY or the file data/okpApiKey.txt.
MATLAB functions#
TOML key |
MATLAB parameter |
Default |
Description |
|---|---|---|---|
|
|
none |
Name of a MATLAB function that constrains the ecModel to anaerobic growth |
|
|
none |
Name of a MATLAB function that changes the protein content of the biomass; it receives the ecModel and the protein content |
|
the parameter name |
none |
Parameters that GECKO uses and geckopy does not use, kept under their MATLAB names. |
geckopy ignores the [matlab] section. The functions are searched on the MATLAB path, to which the code folder of the project is added.
A GECKO 3 adapter class sets the same parameters in MATLAB code; GECKO 3 to GECKO 4 describes how such a class is used and converted.
Troubleshooting#
Problem |
Possible reason |
Solution |
|---|---|---|
|
the key is missing from the tables above, is misspelled, or belongs to no key list of its group, stage or kcat source table |
Correct the key, or place a parameter that GECKO alone uses under |
|
|
Move the setting to |
|
a group lacks one of the two keys, or is a single value in place of a table |
Write the group as a table with |
|
|
Correct the value |
|
the method name is misspelled, or is CatPred or TurNup |
Use the names of OpenKineticsPredictor |
|
a function that needs a target growth rate got none, and the file does not set |
Set |
Error about a preset and stages |
|
Keep one of the two |
|
the folder given holds no |
Give the folder that holds the file |
See also#
Project format 4, the sections of
model_adapter.toml.Kcat assignment, the presets and stages of
[kcat_assignment].Build an ecModel, where the model adapter is created and populated.
Files in the data folder, the other project-wide reference table.