Build & edit ecModel#

MATLAB functions in GECKO/src/change_model of the GECKO toolbox.

Functions#

Function

Summary

addNewRxnsToEC

Add new reactions to an enzyme-constrained model.

applyComplexData

Apply complex subunit stoichiometry to an ecModel.

applyCustomKcats

Apply user-defined kcats to an ecModel.

applyKcatConstraints

Apply kcat-derived enzyme constraints to an ecModel.

findMetSmiles

Query PubChem by metabolite names to obtain SMILES.

getComplexData

Download curated complex stochiometries from Complex Portal.

getKcatAcrossIsozymes

Fill missing kcats from isozymes of the same reaction.

getReactionsFromEnzyme

Get all reactions annotated to a particular enzyme.

getSubsetEcModel

Generate a context-specific ecModel from a general one.

makeEcModel

Expand a conventional GEM into a basic ecModel.

mapRxnsToConv

Map ecModel fluxes back to the conventional starting model.

setKcatForReactions

Change the kcat value for selected reactions.

setProtPoolSize

Set the limit of the total protein usage in the model.

upgradeEcModel

Bring an ecModel made with GECKO 3 to the GECKO 4 format.

Reference#

addNewRxnsToEC#

function [model, rxnsAdded, enzAdded] = addNewRxnsToEC(model, newRxns, varargin)

Add new reactions to an enzyme-constrained model.

Adds new reactions to an enzyme-constrained model. This function is useful to simulate metabolic manipulations done to an organism such as integration of new genes that add a new reaction/pathway.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

newRxns : struct

structure with the new reaction information (see Notes for fields).

Name-Value Arguments

newEnzymes : struct

structure with the new enzymes information (see Notes for fields).

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

Returns

model : struct

ecModel with new reactions.

rxnsAdded : cell

cell array with the reactions added.

enzAdded : cell

cell array with the enzymes added.

Notes

The newRxns structure has the following fields:

  • rxns : cell array with unique strings that identifies each reaction.

  • rxnNames : cell array with the names of each reaction.

  • equations : cell array with equation strings. Decimal coefficients are expressed as "1.2". Reversibility is indicated by "<=>" or "=>".

  • grRules : cell array with the gene-reaction relationship for each reaction. For example "(A and B) or (C)" means that the reaction could be catalyzed by a complex between A & B or by C on its own. All the genes have to be present in model.genes. Add genes with addGenesRaven before calling this function if needed (opt, default '').

The newEnzymes structure has the following fields:

  • enzymes : cell array with uniprot id.

  • genes : cell array with the respective gene.

  • mw : cell array with the MW.

Additional usage notes:

  1. Write equations as follows: 'xylitol[c] + NAD[c] => D-xylulose[c] + NADH[c] + H+[c]' Note that the reversibility defined in the equation will be used to split to construct irreversible reactions (add _REV) and the rules defined will be used to expand the model (add _EXP_n).

  2. After adding the new reactions, setKcatForReactions or applyCustomKcats should be run to add the kcat to the reactions, and subsequently applyKcatConstraints.

Examples

% optional arguments may be given positionally or as name-value pairs:
[model, rxnsAdded, enzAdded] = addNewRxnsToEC(model, newRxns, newEnzymes, modelAdapter);
[model, rxnsAdded, enzAdded] = addNewRxnsToEC(model, newRxns, 'newEnzymes', newEnzymes);

See also

applyKcatConstraints, applyCustomKcats

applyComplexData#

function [model, foundComplex, proposedComplex] = applyComplexData(model, varargin)

Apply complex subunit stoichiometry to an ecModel.

Populates model.ec.rxnEnzMat with subunit stochiometries for protein complexes, based on curated data from the EMBL-EBI Complex Portal.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

Name-Value Arguments

complexInfo : struct

structure as generated by getComplexData. If nothing is provided, an attempt will be made to read data/ComplexPortal.json from the obj.params.path folder specified in the modelAdapter.

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

verbose : logical

true if a summary should be shown in the Command Window (default true).

Returns

model : struct

ecModel where model.ec.rxnEnzMat is populated with subunit stochiometries.

foundComplex : table

complexes that fully matched between the model and the complex data (columns described under Notes).

proposedComplex : table

complexes where the model contained >75% but <100% of the proteins indicated by Complex Portal, or where the model contained more proteins than indicated for that complex in Complex Portal (same columns as foundComplex, plus a percentage match column).

Notes

foundComplex and proposedComplex share the following columns: rxn (reaction identifier), complexID and name (Complex Portal identifiers), genes (gene names of the complex subunits), protID_model (matched protein IDs from the model), protID_complex (protein IDs listed by Complex Portal), and stochiometry (subunit stoichiometry from Complex Portal). proposedComplex has an additional match column with the percentage match between the model proteins and the proposed complex.

Examples

% optional arguments may be given positionally or as name-value pairs:
[model, foundComplex, proposedComplex] = applyComplexData(ecModel, complexInfo, modelAdapter);
[model, foundComplex, proposedComplex] = applyComplexData(ecModel, 'complexInfo', complexInfo);

See also

getComplexData, makeEcModel

applyCustomKcats#

function [model, rxnUpdated, notMatch] = applyCustomKcats(model, varargin)

Apply user-defined kcats to an ecModel.

Reads data/customKcats.tsv in the obj.params.path specified in the model adapter. Alternatively, a customKcats structure can be provided, as specified below.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

Name-Value Arguments

customKcats : struct

structure with custom kcat information (fields described under Notes). If nothing is provided, an attempt will be made to read data/customKcats.tsv from the obj.params.path folder specified in the modelAdapter.

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

Returns

model : struct

ecModel where kcats for defined proteins have been changed.

rxnUpdated : cell

ids list of updated reactions, where new kcats were applied.

notMatch : table

reactions for which the custom information provided has a partial match (at least 50%, but not 100%) with the reaction's GPR rule, for the user to curate manually. Columns: rxns and name (reaction identifier and name), custom enzymes (the proteins specified in customKcats), enzymes in model (the enzymes annotated to the reaction in the model), and rules (the reaction's GPR rule).

Notes

The customKcats structure has the following fields:

  • proteins : protein identifiers, multiple for the same kcat (in case of a protein complex) are separated by ' + '.

  • genes : gene identifiers (optional, not used in matching).

  • gene_name : short gene name (optional, not used in matching).

  • kcat : new kcat value (one per entry).

  • rxns : reaction identifiers, multiple for the same kcat are separated by ',' (see further explanation below).

  • notes : will be appended to model.ec.notes (optional).

  • stoicho : complex stoichiometry, separated by ' + ' (examples: '1' or '3 + 1'), matching the order in proteins field.

Matching order:

  1. reactions are identified by .proteins and .rxns.

  2. reactions are identified by .proteins only (empty .rxns entry); no additional checks are made: is a reaction annotated with these proteins? => its kcat will be updated, irrespective of the exact reaction, direction, substrate, etc.

  3. reactions are identified by .rxns only (empty .proteins entry); no additional checks are made: is a reaction derived from the original reaction identifier => its kcat will be updated, irrespective of the annotated protein.

The customKcats.rxns field reaction identifiers are from the ORIGINAL model, before EXP suffixes were added by makeEcModel. Reaction directionality IS however specified, with a _REV suffix. Example entries:

  • 'r_0001' will match r_0001, r_0001_EXP_1, r_0001_EXP_2 etc., but not r_0001_REV, r_0001_EXP_1_REV etc.

  • 'r_0001_REV' will match r_0001_REV, r_0001_EXP_1_REV, r_0001_EXP_2_REV, etc., but not r_0001, r_0001_EXP_1 etc.

Multiple identifiers should be comma separated (e.g. r_0001, r_0002).

Examples

% optional arguments may be given positionally or as name-value pairs:
[model, rxnUpdated, notMatch] = applyCustomKcats(model, customKcats, modelAdapter);
[model, rxnUpdated, notMatch] = applyCustomKcats(model, 'customKcats', customKcats);

See also

applyKcatConstraints, makeEcModel

applyKcatConstraints#

function model = applyKcatConstraints(model,varargin)

Apply kcat-derived enzyme constraints to an ecModel.

Existing enzyme constraints are first removed (unless updateRxns is provided), and new constraints are defined based on the content of model.ec.kcat.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

Name-Value Arguments

updateRxns : logical or double or cell or char or string

if not all enzyme constraints should be updated, this can be given as either a logical vector of length model.ec.rxns, a vector of model.ec.rxns indices, or a (cell array of) string(s) with model.ec.rxns identifiers. For light models, these reactions should match model.rxns.

Returns

model : struct

ecModel where reactions are constrained by enzyme usage if a kcat value was provided for the reaction-enzyme pair in model.ec.kcat.

Examples

% optional arguments may be given positionally or as name-value pairs:
model = applyKcatConstraints(model, updateRxns);
model = applyKcatConstraints(model, 'updateRxns', updateRxns);

See also

makeEcModel, getKcatAcrossIsozymes, setKcatForReactions

findMetSmiles#

function [model,noSMILES] = findMetSmiles(model, varargin)

Query PubChem by metabolite names to obtain SMILES.

Matches are cached in tutorials/***/data/smilesDB.tsv, which is checked first on subsequent runs so repeated queries are avoided. If the model already has a metSmiles field, non-empty entries are left unchanged.

Parameters

model : struct

a model whose metNames field is used to find the relevant SMILES.

Name-Value Arguments

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

verbose : logical

whether progress should be reported (default true).

Returns

model : struct

model with model.metSmiles specified.

noSMILES : cell

metabolite names for which no SMILES could be found.

getComplexData#

function complexInfo = getComplexData(varargin)

Download curated complex stochiometries from Complex Portal.

Downloads curated complex stochiometries from the EMBL-EBI Complex Portal database. Writes data/ComplexPortal.json in the obj.params.path specified in the model adapter.

Name-Value Arguments

taxonomicID : double

taxonomic identifier for which complex data should be downloaded. Only taxonomic identifiers allowed are those included on Complex Portal: https://www.ebi.ac.uk/complexportal/complex/organisms. If empty, no complex data is downloaded; if 0 (zero), complex data from all organisms in Complex Portal is downloaded.

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

Returns

complexInfo : struct

structure with data downloaded from Complex Portal (fields described under Notes).

Notes

The complexInfo structure has the following fields:

  • complexID : id of the complex on Complex Portal.

  • name : name of the complex on Complex Portal.

  • species : organism containing the complex.

  • geneName : names of the genes in the complex.

  • protID : Uniprot IDs of the proteins in the complex.

  • stochiometry : the complex stochiometry given in the same order as the genes and proteins in geneName and protID.

  • defined : 0 if Complex Portal has no defined stochiometry, 1 if defined subunit stochiometry is given, 2 if complex consists of sub-complexes, whose subunit stochiometries are given.

Examples

% optional arguments may be given positionally or as name-value pairs:
complexInfo = getComplexData(organism, modelAdapter);
complexInfo = getComplexData('taxonomicID', organism);

See also

applyComplexData, makeEcModel

getKcatAcrossIsozymes#

function model = getKcatAcrossIsozymes(model)

Fill missing kcats from isozymes of the same reaction.

For reactions without kcat value (0 in model.ec.kcat), isozymes are found (being based on the same reaction in the conventional GEM), that do have a kcat value assigned. The mean kcat value of these isozymes is then used to fill in model.ec.kcat.

Parameters

model : struct

an ecModel in full GECKO 3 format (with ecModel.ec structure), not GECKO light.

Returns

model : struct

an ecModel with kcat values assigned to isozymes in model.ec.kcat.

Examples

model = getKcatAcrossIsozymes(model);

See also

applyKcatConstraints, setKcatForReactions

getReactionsFromEnzyme#

function [rxns, kcat, idx, rxnNames, grRules] = getReactionsFromEnzyme(ecModel,proteinId)

Get all reactions annotated to a particular enzyme.

Parameters

ecModel : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

proteinId : char

protein identifier, matching ecModel.ec.enzymes case-insensitively.

Returns

rxns : cell

reactions that are associated with this enzyme.

kcat : double

kcat values of the corresponding reactions.

idx : double

index of the reactions in ecModel.ec.rxns.

rxnNames : cell

names of the reactions.

grRules : cell

grRules of the reactions.

Notes

An unmatched proteinId is not an error: all five outputs are returned empty, with no warning. Matching against ecModel.ec.enzymes is case-insensitive.

Examples

[rxns, kcat, idx, rxnNames, grRules] = getReactionsFromEnzyme(ecModel, proteinId);

getSubsetEcModel#

function smallEcModel = getSubsetEcModel(bigEcModel,smallGEM)

Generate a context-specific ecModel from a general one.

Generate a context-specific ecModel (strain/cell-line/tissue) by mapping reactions and genes from a conventional context-specific GEM to a general ecModel (bigEcModel), to yield a context-specific ecModel.

Both models (bigEcModel and the smallGEM) should have derived from the same starting model. If an ecModel with human-GEM 1.15.0 is made (yielding the bigEcModel), then human-GEM 1.15.0 should also be the basis from which the context-specific GEM (smallGEM) was generated by for instance tINIT.

Parameters

bigEcModel : struct

enzyme-constrained version of conventional model of metabolism for a given species.

smallGEM : struct

reduced model (subset of the general model) for a specific strain (microbes) or cell-line/tissues (mammals).

Returns

smallEcModel : struct

enzyme-constrained version of the context-specific model.

Examples

smallEcModel = getSubsetEcModel(bigEcModel,smallGEM);

makeEcModel#

function [model, noUniprot] = makeEcModel(model, varargin)

Expand a conventional GEM into a basic ecModel.

Expands a conventional genome-scale model (in RAVEN format) with enzyme information and prepares the reactions for integration of enzyme usage coefficients. This function contains all the steps that need to be done to get a basic ecModel, without incorporating any kcat values or constraints yet. This function should only have to be run once for a model.

Parameters

model : struct

a model in RAVEN format.

Name-Value Arguments

geckoLight : logical

true if a simplified GECKO light model should be generated (default false).

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

Returns

model : struct

an ecModel in GECKO 3 format, with a model.ec structure where enzyme and kcat information are stored. Protein pseudometabolites and their draw reactions are added to the model, but their usage is not yet implemented (due to absent kcat values at this stage).

noUniprot : cell

genes for which no information could be found in either the Uniprot or, as fallback, the KEGG database.

Notes

The function goes through the following steps:

  1. Remove gene associations from pseudoreactions.

  2. Invert irreversible backwards reactions.

  3. Correct 'rev' vector to match lb and ub vectors.

  4. Convert to irreversible model (splits reversible reactions).

  5. [Skipped with geckoLight:] Expand model to split reactions with 'OR' in grRules (each reaction is then catalyzed by one enzyme (complex)).

  6. Make empty model.ec structure, that will contain enzyme and kcat information. One entry per reaction, where isozymes have multiple entries. This model.ec structure will later be populated with kcat values. For geckoLight the structure is different, where each reaction can have multiple isozymes.

  7. Add enzyme information fields to model.ec structure: MW, sequence. Data is gathered from UniProt, with KEGG used as a fallback for genes that UniProt does not match.

  8. Populate model.ec structure with information from each reaction.

  9. [Skipped with geckoLight:] Add proteins as pseudometabolites.

  10. Add prot_pool pseudometabolite.

  11. [Skipped with geckoLight:] Add usage reactions for the protein pseudometabolites, replenishing from the protein pool (default, can be changed to consider proteomics data at later stage).

  12. Add protein pool reaction, without upper bound.

Note that while protein pseudometabolites, draw & pool reactions might be added to the model, the enzyme usage is not yet incorporated in each metabolic reaction, so enzymes will not be used. applyKcatConstraints incorporates protein pseudometabolites in reactions as enzyme usages by applying the specified kcats as constraints.

The model.ec structure has the following fields:

  • geckoLight : 0 if full model, 1 if light.

  • rxns : reaction identifiers that correspond to model.rxns.

  • kcat : kcat values - not set here.

  • source : specifies where the kcats come from - not set here.

  • notes : notes that can be set by downstream functions - not set here.

  • eccodes : enzyme codes for each enzyme - not set here.

  • genes : the genes involved in the kcats - not necessarily the same as model.genes, since some genes may not be found in databases etc.

  • enzymes : Uniprot protein identifiers for the genes; for a gene that was only matched via the KEGG fallback and has no UniProt accession on its KEGG entry, the bare KEGG gene identifier is used instead.

  • mw : molecular weights of the enzymes.

  • sequence : sequence of the genes/enzymes.

  • concs : concentrations of the enzymes - not set here.

  • rxnEnzMat : matrix of enzymes and rxns.

The full model is split on all ORs in the GPRs, meaning that the reactions will be duplicated for each isozyme. Only the rxns with genes are added. The fields rxns, eccodes, kcat, source and notes will therefore have one entry per reaction. The fields genes, enzymes, mw, sequence and concs will have one entry per gene. The rxnEnzMat is a matrix with reactions and genes, mapping which genes are connected to which reaction (where isozymes have different reactions).

The light model works a bit differently. The model has the same number of rxns as the original model, but expanded since it is reversible + one the extra prot maintenance rxn and one extra prot_pool rxn. However, the ec fields rxns, eccodes, kcat, source and notes are duplicated for each isozyme, sorted the same way as model.rxns. So, in model.ec.rxns, the same reaction will appear several times after one another, one entry per izozyme, with corresponding values for that isozyme. These fields therefore have the same length as for the full model. The fields genes, enzymes, mw, sequence and concs are the same here as in the full model. The rxnEnzMat maps the model.ec.rxns entries to genes and is therefore of the same size as for the full model.

Examples

% optional arguments may be given positionally or as name-value pairs:
[model, noUniprot] = makeEcModel(model);
[model, noUniprot] = makeEcModel(model, 'geckoLight', true);

See also

applyKcatConstraints, applyComplexData

mapRxnsToConv#

function [mappedFlux, enzUsageFlux, usageEnz] = mapRxnsToConv(ecModel, model, fluxVect)

Map ecModel fluxes back to the conventional starting model.

A vector (or matrix) of fluxes is mapped to the reactions in the conventional starting model that was used to construct the ecModel. It is essential that the provided conventional model is indeed the model that was used to initiate ecModel reconstruction.

Parameters

ecModel : struct

an ecModel in GECKO 3 format (with ecModel.ec structure), that was used to obtain fluxVect.

model : struct

the starting model for ecModel, to which the reactions should be mapped.

fluxVect : double

vector or matrix of flux values, matching ecModel.rxns.

Returns

mappedFlux : double

vector or matrix of flux values, matching model.rxns.

enzUsageFlux : double

vector or matrix of flux values from enzyme usage reactions, as these are absent from mappedFlux.

usageEnz : cell

cell array with protein IDs, matching enzUsageFlux.

Examples

[mappedFlux, enzUsageFlux, usageEnz] = mapRxnsToConv(ecModel, model, fluxVect);

See also

ecFVA

setKcatForReactions#

function ecModel = setKcatForReactions(ecModel,rxnIds,kcat)

Change the kcat value for selected reactions.

Changes the kcat value in ecModel.ec.kcat for selected reactions. applyKcatConstraints needs to be run afterwards to transfer the kcat values into the S-matrix.

Parameters

ecModel : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

rxnIds : char or cell

reaction identifier matching ecModel.ec.rxns. If the EXP suffix is not included, and there are multiple expanded (isozymic) reactions, then all of those will have their kcat changed. If rxnIds includes a EXP suffix, then only that specific reaction will have its kcat changed. If multiple rxnIds are provided as a cell array, then the above applies to each rxnIds individually.

kcat : double

the new kcat value.

Returns

ecModel : struct

ecModel where selected kcat values in ecModel.ec.kcat are changed, but not yet applied to the S-matrix (will require to run applyKcatConstraints). ecModel.ec.source for the changed reactions will read 'setKcatForReactions'.

Examples

ecModel = setKcatForReactions(ecModel, rxnIds, kcat);

See also

applyKcatConstraints, getKcatAcrossIsozymes

setProtPoolSize#

function model = setProtPoolSize(model, varargin)

Set the limit of the total protein usage in the model.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure).

Name-Value Arguments

Ptot : double

total cellular protein content in g/gDCW. If not specified, the value will be read from the model adapter. If not specified in model adapter, 0.5 g/gDCW is assumed.

f : double

estimated fraction of enzymes in the model. If not specified, the value will be read from the model adapter. If not specified in model adapter, 0.5 is assumed.

sigma : double

estimated saturation factor. If not specified, the value will be read from the model adapter. If not specified in model adapter, 0.5 is assumed.

modelAdapter : ModelAdapter

a loaded model adapter (default: the current default model adapter).

Returns

model : struct

ecModel with protein pool constraint set.

Examples

% optional arguments may be given positionally or as name-value pairs:
model = setProtPoolSize(model, Ptot, f, sigma, modelAdapter);
model = setProtPoolSize(model, 'Ptot', Ptot);

See also

makeEcModel

upgradeEcModel#

function [model, changed] = upgradeEcModel(model)

Bring an ecModel made with GECKO 3 to the GECKO 4 format.

GECKO 3 defined the protein usage reactions (usage_prot_, prot_ -> prot_pool) and the protein pool exchange (prot_pool_exchange, prot_pool ->) in the reverse direction, used with negative flux. GECKO 4 defines them forward (prot_pool -> prot_, -> prot_pool), so that an enzyme's usage is the positive flux of its usage reaction. This turns each reaction that is still reverse: its column of S, its bounds and its objective coefficient change sign. Reactions already forward are left as they are, so calling it again changes nothing. Flux values of the model (fluxes of usage reactions and the pool exchange) change sign with it. The ecModel format (annotation.gecko_format, see saveEcModel) becomes 4 when it is missing or lower. geckopy has the same (upgrade_ec_model).

Parameters

model : struct

an ecModel.

Returns

model : struct

the ecModel in the GECKO 4 format.

changed : cell

the reactions that were turned.

Examples

ecModel = upgradeEcModel(readYAMLmodel('ecYeastGEM_GECKO3.yml'));

See also

upgradeGECKOproject, makeEcModel, setProtPoolSize