GECKO 3 to GECKO 4#
GECKO 4 keeps the ecModel structure of GECKO 3 (ecModel.ec, the MW/kcat coefficient) and changes the direction of the protein reactions, how a project is configured, and how kcats are gathered and assigned. GECKO 3.0 is the version described in the published Nature Protocols pipeline (see Citations). The sections below follow the risk of a wrong result for a GECKO 3 script or project. geckopy implements the GECKO 4 behaviour described here.
Changes that pass without an error
A GECKO 3 script keeps running after each change in this box and returns a different result.
The protein pool exchange and the enzyme usage reactions run forward, so bounds and fluxes of
prot_pool_exchangeandusage_prot_*have the opposite sign (PR #419).fuzzyKcatMatchingdivides a BRENDA kcat by the coefficient of the substrate the kcat was measured on. GECKO 3 divided by the smallest coefficient in the reaction.assignKcatsandcollectKcatsuse the presetbrenda_ec_treewhenmodel_adapter.tomlsets no other.calculateFfactoraverages each protein over the samples in which it is measured.sigmaFitterreturns the smallest sigma within a tolerance of the smallest error, and the returned ecModel has the protein pool of that sigma (see below the first table).flexibilizeEnzConcskeeps an upper bound that is higher than the new bound, and stops after a total number of iterations.
Changes by consequence#
Results that change without an error#
Change |
GECKO 3 |
GECKO 4 |
Action |
|---|---|---|---|
Direction of protein reactions |
|
both run forward, and the usage of an enzyme is the positive flux of its usage reaction |
Reverse the sign of bounds and fluxes read from these reactions. |
Substrate of a BRENDA kcat |
the kcat is divided by the smallest coefficient in the reaction |
the kcat is divided by the coefficient of the substrate that matched |
Rebuild the kcat list. Reactions that are not written per the measured substrate get a lower kcat |
Default kcat assignment |
|
|
Set |
Protein fraction |
|
the average is over the samples in which the protein is measured |
Recalculate |
Enzyme bounds of |
the new upper bound of an enzyme replaces the old bound, also when the old bound is higher; the iterations have no total limit |
an upper bound is never lowered, and the iterations have a total limit (see below the table) |
Check the warnings and |
File name of |
|
a name ending in |
none |
Sigma fit |
|
it returns the smallest sigma within a tolerance of the smallest error (see below the table), and an ecModel whose protein pool is set for that sigma |
Refit when the growth rate is flat over a range of sigma; a script that called |
flexibilizeEnzConcs stops and prints a message after a total of (iterPerEnzyme + 1) × (number of measured enzymes) iterations, with 1000 for iterPerEnzyme when it is 0. On an infeasible input model, it warns with the identifier flexibilizeEnzConcs:infeasible and returns flexEnz with empty fields. sigmaFitter returns the smallest sigma whose growth rate differs from the target by at most the smallest difference plus 1e-9 times the growth rate at the smallest difference; geckopy fit_sigma has no tolerance in its default grid.
Changes that raise an error#
The changes in this table, and calls of removed functions (see Removed), stop a GECKO 3 script.
Change |
Condition |
Action |
|---|---|---|
|
the sum of |
Correct |
|
|
Update GECKO |
Adapter keys |
|
Remove or rename the key, or place a key that GECKO uses and geckopy does not use under |
Options of |
an option name that the function does not have |
Correct the option name |
|
every call in MATLAB: the functions are deprecated and raise an error |
Use |
|
the target growth rate is not above 0 |
Give a growth rate above 0 |
|
the model has no |
Give an ecModel made by |
|
the model has no optimal solution |
Make the model feasible first |
|
a stage lists |
Run |
Changes of the project#
A GECKO 3 project is configured by an adapter class and keeps its kcats in data/DLKcat.tsv, data/customKcats.tsv and in the variables of the script. A GECKO 4 project is configured by model_adapter.toml, keeps each kcat source in its own file in data/kcats, and records the ecModel format in the saved model. assignKcats writes its decisions to output/<model id>_kcatDecisions.tsv, with column names in snake_case (ec_rxn, spread_log10, sd_log10); the table that collectKcats returns keeps camelCase names. Project format 4 describes the files, and Upgrade a GECKO 3 project the steps that convert a project.
Functions with name-value arguments also take them positionally, in the GECKO 3 order: loadEcModel(filename, modelAdapter) and loadEcModel('filename', filename) are equivalent. A call uses one of the two forms for all its optional arguments.
Adapter classes#
A GECKO 3 adapter class keeps working. It sets obj.params with the MATLAB names of Model adapter parameters, and ModelAdapterManager.setDefault takes the path of its .m file. convertAdapterToToml writes the parameters of a class as model_adapter.toml and lists the methods that the class overrides and the file cannot express. The option 'adapterFormat','class' of createGECKOproject creates a project with a class; both the option and adapter classes as project format are deprecated (see Deprecated).
A class that needs code beyond the file can read its parameters from the file in the constructor:
obj.params = loadAdapterParams(fullfile(projectPath, 'model_adapter.toml'));
In geckopy, a subclass of ModelAdapter overrides get_spontaneous_reactions, get_uniprot_compatible_genes, get_uniprot_ids_from_table, get_kegg_compatible_genes, get_brenda_db_folder or get_phyl_dist_path. It is instantiated explicitly; from_folder does not discover it.
New functions#
The table lists a selection.
Group |
Functions |
|---|---|
Kcat sources |
|
Kcat assignment |
|
Databases |
|
Project and model upgrade |
|
Adapter |
|
Kcat tuning |
|
Proteomics |
|
Analysis |
|
getEnzymeBottlenecks solves the model again after raising the usage bound of each enzyme that runs at its bound, and ranks the enzymes by the rise of the objective. The shadow price is reported and does not enter the order.
relaxProteomicsGreedy returns [result, model], with the relaxed model as second output. relaxEnzConcs raises the enzyme bounds with the least total fold increase in one linear program.
levelComplexConcs gives the subunits of a multi-subunit complex one abundance. The complex is then not capped by its least abundant subunit. It runs after fillEnzConcs and before constrainEnzConcs.
kcat prediction goes through the hosted OpenKineticsPredictor (OKP) service, through kcatsFromOKP. The default OKP method ([okp] method) is KinForm-H, and the okp stage of the presets uses the methods of [kcat_sources.okp] methods, by default KinForm-H alone. kcatsFromDLKcat uses its DLKcat method unless data/DLKcat.tsv exists, or the option 'via', 'docker' selects a local run in the Docker image. The DLKcat Docker context is not part of the GECKO repository (src/dlkcat-gecko is removed).
Removed#
Removed |
Replacement |
|---|---|
BRENDA files in |
|
|
|
|
|
|
|
|
|
|
copies in |
The removed functions in the table, except truncateValues, anaerobicModel_GECKO and changeMedia, have a stub in src/deprecated that raises an error naming the replacement. upgradeGECKOproject lists the lines of a project's scripts that call them.
Deprecated#
updateProtPool, applyCustomKcats, runDLKcat, writeDLKcatInput, readDLKcatOutput and the option 'adapterFormat', 'class' of createGECKOproject print a deprecation warning, and so does the first adapter class loaded in a MATLAB session, unless it subclasses TomlAdapter. Everything in the table is removed in a future release.
Deprecated |
Replacement |
|---|---|
|
|
|
|
|
|
Adapter classes as project format: |
|
Renamed functions#
The old name of each function in the table calls the new function and prints a deprecation warning. The old names are in src/deprecated and are removed in a future release.
GECKO 3 name |
GECKO 4 name |
Reason |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
the function writes |
|
|
merges kcat lists of any number of sources |
geckopy names a counterpart in snake_case; the prefix get is dropped for some (enzyme_usage for getEnzymeUsage, pfba_enzymes for getPfbaEnzymes) and kept by others (merge_kcats for mergeKcats). The counterpart of createGECKOproject is the command geckopy init, and the counterpart of upgradeGECKOproject is geckopy upgrade. MATLAB and Python lists the full mapping.
Staying on GECKO 3#
The last GECKO 3 release is v3.2.5.
git clone https://github.com/SysBioChalmers/GECKO
cd GECKO
git checkout v3.2.5
Run GECKOInstaller.install in MATLAB.
Download the v3.2.5 archive from the GitHub releases page, extract it and run GECKOInstaller.install.
The Add-On manager distributes the latest release. Uninstall the Add-On (GECKOInstaller.uninstall, or the Add-On manager) and install v3.2.5 with git or the ZIP archive.
Installation describes the installation methods.
Earlier versions#
GECKO 1 (Sánchez et al., 2017) and GECKO 2 (Domenzain et al., 2022) share one ecModel structure, which differs from GECKO 3 and GECKO 4:
Enzyme and kcat information is spread over several model fields. From GECKO 3,
ecModel.ec(Python:ec_model.ec) collects it.Enzymes enter the S-matrix as
1/kcat, with the molecular weight in the protein exchange reactions. From GECKO 3 the coefficient isMW/kcat(see Choose the ecModel structure).The YAML format of GECKO 3 and GECKO 4 retains the full model content. GECKO 1 and GECKO 2 have no such format.
Functions of GECKO 3 and GECKO 4 do not work on a GECKO 1 or GECKO 2 ecModel, and the reverse. geckopy supports GECKO 4 ecModels.
The last GECKO 2 release is 2.0.3, and the gecko2 branch takes fixes for it. The GECKO 1 release is cited in Citations.
Troubleshooting#
Problem |
Possible reason |
Solution |
|---|---|---|
Deprecation warning |
the script calls a GECKO 3 name |
Use the GECKO 4 name from Renamed functions |
Warning when |
the ecModel was saved by GECKO 3 and its protein reactions run in reverse |
|
An enzyme usage flux is negative |
the model was not upgraded |
Run |
Error that names a key of |
the key is not in |
Place a key that GECKO uses and geckopy does not use under |
A rebuilt ecModel has other kcats than the GECKO 3 model |
the default preset and the substrate of BRENDA kcats changed |
Use |