Choose the ecModel structure#
makeEcModel turns a conventional genome-scale metabolic model (GEM) into an enzyme-constrained model (ecModel) without kcats: reversible reactions are split by direction, the enzymes of each reaction are recorded in the ec structure, and the protein pool is added. The result is a full or a light ecModel without kcats, a list of the genes that have no protein data, and, for an organism in the Complex Portal, the subunit stoichiometry of the enzyme complexes.
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: Build an ecModel, step 1"]):::ctx
B1["ModelAdapterManager.setDefault<br/>loadConventionalGEM"]
B3{"Full or light?"}
B4["makeEcModel<br/>calls loadDatabases"]
B5["makeEcModel, light<br/>calls loadDatabases"]
B6["getComplexData<br/>applyComplexData"]:::opt
PV --> B1 --> B3
B3 -->|full| B4 --> B6
B3 -->|light| B5 --> B6
NX(["Next: Choose the kcat sources"]):::ctx
B4 --> NX
B5 --> NX
B6 --> NX
click PV href "first-ecmodel.html"
click NX href "kcat-sources.html"
---
config:
flowchart:
useMaxWidth: false
---
flowchart TB
classDef opt stroke-dasharray: 5 4
classDef ctx fill:transparent,stroke-dasharray: 2 3
PV(["Previous: Build an ecModel, step 1"]):::ctx
B1["ModelAdapter.from_folder<br/>load_conventional_gem"]
B3{"Full or light?"}
B4["make_ec_model<br/>downloads the UniProt and KEGG data;<br/>load_uniprot_tsv, load_kegg_tsv read them"]
B5["make_ec_model, light<br/>downloads the UniProt and KEGG data;<br/>load_uniprot_tsv, load_kegg_tsv read them"]
B6["get_complex_data<br/>apply_complex_data"]:::opt
PV --> B1 --> B3
B3 -->|full| B4 --> B6
B3 -->|light| B5 --> B6
NX(["Next: Choose the kcat sources"]):::ctx
B4 --> NX
B5 --> NX
B6 --> NX
click PV href "first-ecmodel.html"
click NX href "kcat-sources.html"
Functions#
MATLAB |
Python |
Note |
|---|---|---|
|
|
read |
read |
||
load the GEM named by |
||
build a full or a light ecModel |
||
download complex stoichiometries from the Complex Portal |
||
write the subunit stoichiometry of matching complexes to |
Setup#
The project folder has a model_adapter.toml (see Build an ecModel). The build reads these adapter keys, described in Model adapter parameters:
conv_gem: path of the conventional GEM.enzyme_comp: name of the compartment (an entry ofmodel.compNames) that receives the protein pseudometabolites.uniprot.id,uniprot.type,uniprot.gene_id_field,uniprot.reviewed: the UniProt query that givesdata/uniprot.tsv.kegg.id,kegg.gene_id: the KEGG organism and field that givedata/kegg.tsv.complex.taxonomic_id: the taxonomy identifier for the Complex Portal.
The data files are described in Files in the data folder.
Full or light ecModel#
Both structures add the enzyme cost of a reaction as protein mass drawn from the protein pool. They differ in how isozymes and single enzymes appear in the model:
Property |
Full ecModel |
Light ecModel |
|---|---|---|
Isozymes |
each isozyme gets its own copy of the reaction ( |
the reaction is not copied; |
Enzymes in the model |
one pseudometabolite |
none |
Enzyme cost of a reaction |
the reaction consumes its enzymes; the enzymes draw on |
the reaction consumes |
Size of the model |
larger than the conventional GEM by the isozyme copies and one reaction per enzyme |
the irreversible conventional GEM plus |
Needed for |
proteomics constraints, enzyme usage and bottleneck analysis |
A light ecModel cannot be turned into a full one, or the reverse; the choice is made when makeEcModel runs, and it is stored in the ecModel (ec.geckoLight in MATLAB, ec.gecko_light in Python, gecko_light in the YAML file).
Build a full ecModel unless the size of the full model makes the simulations too slow and no task in the next table is needed. These tasks need the per-enzyme pseudometabolites and usage reactions of a full ecModel:
Task |
MATLAB |
Python |
|---|---|---|
Constrain enzymes with proteomics |
|
|
Enzyme usage and bottlenecks |
|
|
Fill kcats from other isozymes |
|
|
Add reactions to an ecModel |
|
|
Convert |
|
|
On a light ecModel, assignKcats and collectKcats skip the step that fills kcats from other isozymes. A custom.tsv written from a full ecModel applies to a light ecModel too. applyKcatConstraints, getStandardKcat, applyComplexData, sensitivityTuning and getSubsetEcModel work on both structures.
The tutorial script tutorials/full_ecModel/code/plotlightVSfull.m of GECKO builds a light and a full ecModel of yeast-GEM with the same kcats, maximises growth in both, and plots the two flux distributions mapped to the reactions of the GEM.
Build the ecModel#
ModelAdapterManager.setDefault('path/to/project');
model = loadConventionalGEM();
% Full ecModel
[ecModel, noUniprot] = makeEcModel(model);
% Light ecModel
[ecModel, noUniprot] = makeEcModel(model, 'geckoLight', true);
makeEcModel needs a model in RAVEN format. It raises an error for a model with the field rules or modelID, which a model loaded with the COBRA Toolbox has; convert such a model with ravenCobraWrapper.
from geckopy import ModelAdapter, load_conventional_gem, make_ec_model
adapter = ModelAdapter.from_folder("path/to/project")
model = load_conventional_gem(adapter)
# Full ecModel
ec_model = make_ec_model(model, adapter)
# Light ecModel
ec_model = make_ec_model(model, adapter, gecko_light=True)
make_ec_model returns a new EcModel and leaves model unchanged. It raises a ValueError when it is called on an ecModel whose ec is already filled.
The ecModel has no kcats yet: ec.kcat is 0 for every row, and no metabolic reaction consumes an enzyme (full ecModel) or prot_pool (light ecModel). Choose the kcat sources fills the kcats and applies them.
Steps of makeEcModel#
makeEcModel (Python: make_ec_model) runs these steps in order:
Step |
Full |
Light |
|---|---|---|
Remove the gene associations of pseudo-reactions: reactions whose name contains |
yes |
yes |
Reverse the reactions with a lower bound below 0 and an upper bound of 0 |
yes |
yes |
Split each reversible reaction, except exchange reactions, into a forward reaction and a reverse reaction with the suffix |
yes |
yes |
Split each reaction with isozymes ( |
yes |
no |
Create |
yes |
yes |
Record which enzymes each reaction needs in |
yes |
yes |
Add a pseudometabolite |
yes |
no |
Add the pseudometabolite |
yes |
yes |
Add a reaction |
yes |
no |
Add |
yes |
yes |
The upper bound of prot_pool_exchange stays 1000 until Set the protein pool sets it.
The identifiers that these steps add must be new, so makeEcModel raises an error when a metabolite identifier of the GEM starts with prot_, or when a reaction identifier starts with usage_prot_ or prot_pool, or ends with _REV or _EXP_<digits>.
Match genes to UniProt and KEGG#
makeEcModel matches each gene of the model to a row of data/uniprot.tsv, on the field set by uniprot.gene_id_field. When data/uniprotConversion.tsv exists, the genes are first converted to UniProt identifiers with that table, and the match is on the UniProt identifier. A gene that UniProt does not match is looked up in data/kegg.tsv, on the field set by kegg.gene_id. For a gene found in KEGG, ec.enzymes gets the UniProt accession of the KEGG row, or the KEGG gene identifier when the row has no accession; a warning lists these genes.
A gene that matches in neither file has no enzyme in the ecModel. A subunit of a complex without a match is left out of the complex, and the other subunits still give the reaction its enzyme cost. A reaction, or in a full ecModel an isozyme copy of a reaction, whose genes all have no match has an empty row in ec.rxnEnzMat and no enzyme cost. In a light ecModel, such an isozyme is left out when the isozyme with the smallest cost is selected.
noUniprot, the second output of makeEcModel, lists the genes that match neither file, and a warning gives their number.
makeEcModel downloads a missing data/uniprot.tsv or data/kegg.tsv through loadDatabases, with the [uniprot] and [kegg] values of the adapter.
make_ec_model returns no list. It logs a warning with the number of genes that match neither file and the first five, and adds a note under rxn.notes["geckopy_warning"] to every reaction that has such a gene.
make_ec_model downloads a missing data/uniprot.tsv or data/kegg.tsv with the [uniprot] and [kegg] values of the adapter, through load_uniprot_tsv and load_kegg_tsv. It raises a FileNotFoundError when data/uniprot.tsv is missing and uniprot.id is empty. The arguments uniprot_db and kegg_db take databases loaded beforehand.
The commands geckopy uniprot-download and geckopy kegg-download download the same files, with identifiers and options given on the command line; they do not read the adapter.
In both languages, a file that exists is not downloaded again: after a change of uniprot.id, delete data/uniprot.tsv before the build.
Many genes without a match mean that the UniProt query or the gene identifier field does not fit the gene identifiers of the GEM. Compare a few gene identifiers of the GEM with the gene column of data/uniprot.tsv, then change uniprot.id, uniprot.type or uniprot.gene_id_field, or add data/uniprotConversion.tsv (see Find the UniProt and KEGG parameters).
Find the UniProt and KEGG parameters#
data/uniprot.tsv gives the molecular weight and the sequence of each enzyme, and a GEM without it has no enzyme data. data/kegg.tsv is optional: it fills genes that UniProt does not match, and EC numbers. The query must return gene identifiers in the same style as the genes of the GEM.
UniProt proteome or taxonomy.
uniprot.idhas no default: without it and withoutdata/uniprot.tsv, the build raises an error that names the key (MATLAB:loadDatabases:noUniprotID). Withuniprot.type = "proteome",uniprot.idis a proteome identifier from UniProt proteomes; choose the reference proteome when the organism has several proteomes. Withuniprot.type = "taxonomy",uniprot.idis a taxonomy identifier; choose the most specific one, for example the strain (559292 for S. cerevisiae S288C) in place of the species (4932). A proteome gives fewer duplicate matches between genes and proteins.uniprot.reviewed = truerestricts the query to Swiss-Prot entries; the defaultfalsealso includes unreviewed entries (geckopy uniprot-download: the option--reviewed-onlyrestricts it).UniProt gene identifier field.
uniprot.gene_id_fieldis the UniProt field whose values match the genes of the GEM. The page of one protein on uniprot.org shows its gene names under "Names & Taxonomy"; for yeast-GEM, which uses identifiers such asYFL026W("Ordered locus names"), the field isgene_oln.KEGG organism code.
kegg.idis the code from the KEGG organism list, for examplesceorhsa. The default is empty: the build then downloads no KEGG file, prints a warning and uses no KEGG data, which is the setting for an organism that is not in KEGG.KEGG gene identifier. With
kegg.gene_id = "kegg", the genes are matched on the KEGG gene identifier. Another value is read from the "Other DBs" links of each KEGG gene entry, for exampleEnsemblfor the gene identifiers of Human-GEM. A KEGG entry without a UniProt link is not written todata/kegg.tsv.
When no UniProt field matches the gene identifiers, data/uniprotConversion.tsv maps them: a header row, then one row per gene with the gene identifier and the UniProt identifier, tab-separated. data/kegg.tsv has both identifiers in its first and third columns (UniProt, gene, KEGG gene, comma-separated, no header), which gives the table for an organism whose GEM uses KEGG gene identifiers, such as E. coli iML1515 with b0008:
params = ModelAdapterManager.getDefault().getParameters();
DB = loadDatabases('kegg');
fID = fopen(fullfile(params.path, 'data', 'uniprotConversion.tsv'), 'w');
fprintf(fID, '%s\t%s\n', 'genes', 'uniprot');
output = transpose([DB.kegg.keggGene, DB.kegg.uniprot]);
fprintf(fID, '%s\t%s\n', output{:});
fclose(fID);
import pandas as pd
data = adapter.params.path / "data"
columns = ["uniprot", "gene", "kegg_gene", "ec", "mw", "pathway", "sequence"]
kegg = pd.read_csv(data / "kegg.tsv", header=None, names=columns)
kegg[["kegg_gene", "uniprot"]].rename(columns={"kegg_gene": "genes"}).to_csv(
data / "uniprotConversion.tsv", sep="\t", index=False,
)
For an organism in neither UniProt nor KEGG, write data/uniprot.tsv (and, if needed, data/kegg.tsv) by hand, with the columns of the files of the full_ecModel tutorial. The identifiers can be invented, but the molecular weights and sequences must be correct, because the enzyme costs and the kcat predictions use them.
Add the stoichiometry of enzyme complexes#
makeEcModel gives every subunit of an enzyme complex the stoichiometry 1. The Complex Portal has curated subunit stoichiometries for a limited set of organisms; the link lists them. For an organism in the list, set complex.taxonomic_id to its taxonomy identifier and add the data. For another organism, keep the stoichiometry of 1, or write data/ComplexPortal.json from other databases or the literature.
complexInfo = getComplexData();
[ecModel, foundComplex, proposedComplex] = applyComplexData(ecModel, complexInfo);
getComplexData reads the taxonomy identifier from the adapter, or takes it as the argument taxonomicID; 0 downloads the complexes of all organisms. Without a taxonomy identifier, it warns and returns an empty structure. It writes data/ComplexPortal.json. applyComplexData without complexInfo reads that file, and runs getComplexData when the file does not exist. foundComplex and proposedComplex are tables, and the number of each is printed.
from geckopy import apply_complex_data, get_complex_data
json_path = adapter.params.path / "data" / "ComplexPortal.json"
get_complex_data(adapter.params.complex.taxonomic_id, write_to=json_path)
apply_complex_data(ec_model, path=json_path)
get_complex_data takes the taxonomy identifier (0 for all organisms) and returns the complexes; write_to saves them. Without a taxonomy identifier (None), it logs a warning and returns an empty list. apply_complex_data changes ec_model in place, logs the number of full and proposed matches, and logs each proposed complex as a warning. When at least one complex matches and apply=True (the default), it runs apply_kcat_constraints afterwards.
A complex is applied to a reaction when its proteins and the enzymes of the reaction are the same set. For a reaction with more than one enzyme and no exact match, a complex is proposed, not applied, in two cases: the complex contains all enzymes of the reaction and more subunits; or the complex contains at least 75 % (and less than 100 %) of the enzymes of the reaction and has no more subunits than the reaction has enzymes, so it can contain subunits that the reaction lacks (Python: the keyword min_match_to_propose, default 0.75). A reaction can have a proposal for each case, so two rows in proposedComplex (Python: two warnings). Read the proposed complexes: a missing subunit in the gene rule of the GEM can be the reason, and a curated gene rule then gives an exact match in the next build.
The stoichiometry changes ec.rxnEnzMat (Python: ec.rxn_enz_mat). The enzyme cost in the reactions follows from it when the kcats are applied, so add the complex data before the kcats are assigned.
Troubleshooting#
Problem |
Possible reason |
Solution |
|---|---|---|
Error that identifiers in |
the GEM has identifiers that start with |
rename those identifiers in the GEM |
Error that the compartment cannot be found in |
|
set |
Error that none of the proteins in |
the UniProt and KEGG parameters do not fit the gene identifiers |
|
MATLAB error that the model was likely loaded with the COBRA Toolbox |
the model has the field |
load it with |
An error that names a light ecModel (Python: |
the function needs a full ecModel |
build a full ecModel |
Warning that no taxonomic identifier is specified, and no complex data |
|
set it in |
Error that no data could be gathered from the Complex Portal |
the Complex Portal has no complexes for this taxonomy identifier |
skip the complex data |
The rows of |
the rows have the prefix |
remove the first four characters |
See also#
Introduction to ecModels, for the enzyme constraint that both structures encode.
Choose the kcat sources, the next step.
Constrain enzymes with proteomics and Enzyme usage and bottlenecks, which need a full ecModel.
ecModel YAML format, for
gecko_lightand theecfields in the saved file.