Gather kcats#

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

Functions#

Function

Summary

assignKcats

Assign kcats from the kcat source files and apply them.

assignKcatValues

Select one kcat value per reaction and write to model.ec.

collectKcats

Decide one kcat per reaction from the kcat source files.

convertCustomKcats

Convert data/customKcats.tsv into data/kcats/custom.tsv.

ecStatsFromBrenda

Summarise loadBRENDAdata's output per EC number, for

ecTreeEstimate

EC-tree kcat estimates for EC numbers.

extractEnzymeSubstratePairs

The enzyme-substrate pairs of an ecModel's reactions.

fetchOpenKineticsPredictor

Fetch and parse an OpenKineticsPredictor job.

fuzzyKcatMatching

Match model EC numbers and substrates to BRENDA kcats.

getEcRxnKeys

Build-independent keys of the model.ec reactions.

getStandardKcat

Assign standard kcat and MW to reactions without enzymes.

kcatAssignmentConfig

The kcat assignment settings of a model adapter.

kcatsFromBrenda

Gather kcats from BRENDA and keep them as a source file.

kcatsFromDLKcat

Gather kcats from DLKcat and keep them as a source file.

kcatsFromECTree

Estimate kcats from the EC tree and keep them as a source file.

kcatsFromHomologs

Estimate kcats from measured homologs and keep them as a source file.

kcatsFromOKP

Gather kcats from OpenKineticsPredictor and keep them as a source file.

loadBrendaMeasurements

Load the BRENDA measurement table.

loadKcatSource

Read a kcat source file and map its rows to an ecModel.

mergeDLKcatAndFuzzyKcats

Merge DLKcat and BRENDA fuzzy matching results.

mergeKcats

Merge any number of kcatLists, keeping the highest-priority

readDLKcatOutput

Read the DLKcat output file into a kcatList structure.

readOpenKineticsPredictorOutput

Read OpenKineticsPredictor output to kcatList.

removeStandardKcat

Remove the standard pseudoenzyme and standard kcats.

resolveOkpApiKey

Resolve the OpenKineticsPredictor API key.

reviewKcatAssignment

Flag kcat assignments that deserve a second look.

runDLKcat

Run DLKcat to predict kcat values from a Docker image.

saveKcatSource

Write a kcatList to a kcat source file of the project.

submitOpenKineticsPredictor

Submit a kcat prediction job to OpenKineticsPredictor.

updateKcatSources

Gather the kcat sources that the configuration needs.

writeDLKcatInput

Prepare and write the input file for DLKcat.

writeOpenKineticsPredictorInput

Write input file for OpenKineticsPredictor.

Reference#

assignKcats#

function [model, decisions, report] = assignKcats(model, varargin)

Assign kcats from the kcat source files and apply them.

Decides one kcat per reaction from the kcat source files in data/kcats, as [kcat_assignment] in model_adapter.toml sets (see collectKcats), writes model.ec.kcat and model.ec.source, and applies the kcat constraints (applyKcatConstraints). Any kcats the model had are replaced: the source files are the input, and nothing in the model is written back to them.

Parameters

model : struct

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

Name-Value Arguments

modelAdapter : ModelAdapter

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

writeReport : logical

write the decisions to output/_kcatDecisions.tsv (default true).

Returns

model : struct

the ecModel with the assigned kcats applied.

decisions, report

as returned by collectKcats.

Examples

updateKcatSources(ecModel);   % gather what the configuration needs
ecModel = assignKcats(ecModel);

See also

collectKcats, updateKcatSources, applyKcatConstraints

assignKcatValues#

function [model, rxnIdx] = assignKcatValues(model,kcatList,varargin)

Select one kcat value per reaction and write to model.ec.

From a kcatList with predicted or suggested kcat values, where each reaction may have multiple entries, one kcat value is selected and written to model.ec.kcat. Zero values are discarded from the start. By default, the maximum value is chosen, but alternatives are available. The kcatList structure is an output of e.g. readDLKcatOutput, readGotEnzymesOutput, readManualKcatList.

Parameters

model : struct

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

kcatList : struct

structure array with separate entries for each kcat value, with the following fields:

  • source : e.g. 'DLKcat' or 'gotenzymes'.

  • rxns : reaction identifiers, matching model.ec.rxns.

  • genes : gene identifiers, matching model.ec.genes.

  • substrates : substrate names, matching model.metNames.

  • kcats : predicted kcat value in /sec.

Name-Value Arguments

criteria : char

which kcat value should be selected if multiple values are provided. Options: 'max', 'min', 'median', 'mean' (default 'max'). The written model.ec.source is taken from the matching entry for 'max'/'min'; for 'median'/'mean', where the selected value need not equal any single input, it is taken from the first entry instead (arbitrary but deterministic, since an aggregate has no single "winning" source).

overwrite : char

whether existing kcat values should be overwritten. Options: 'true', 'false', 'ifHigher'. The last option will overwrite only if the new kcat value is higher (default 'true').

Returns

model : struct

ecModel with updated model.ec.kcat and model.ec.source.

rxnIdx : double

list of reaction indices (matching model.ec.rxns), to indicate which kcat values have been changed.

Examples

% optional arguments may be given positionally or as name-value pairs:
[model, rxnIdx] = assignKcatValues(model, kcatList);
[model, rxnIdx] = assignKcatValues(model, kcatList, 'criteria', 'mean');

See also

readDLKcatOutput, mergeDLKcatAndFuzzyKcats, applyKcatConstraints

collectKcats#

function [decisions, report, ecModel] = collectKcats(model, varargin)

Decide one kcat per reaction from the kcat source files.

Combines the kcat source files in data/kcats (see kcatsFromBrenda, kcatsFromDLKcat, kcatsFromOKP and saveKcatSource) as [kcat_assignment] in model_adapter.toml sets, without changing the model given. assignKcats applies the decisions.

The order is a preset or a list of stages:

[kcat_assignment]
preset = "brenda_ec_tree"    # the default; or ec_tree_homologs, ec_tree_okp, okp,
                             # gecko_median, gecko_classic
isozymes = true              # fill from isozymes after the stages
standard = true              # standard kcat for the rest

# instead of a preset:
[[kcat_assignment.stage]]
action = "select"            # or "combine"
sources = ["custom", "database_top", "ec_tree"]
criteria = "max"             # select: among several values of one source
top_origin_limit = 1

[kcat_sources.okp]
methods = ["CataPro", "UniKP"]   # the okp source group

A stage decides the reactions that are still open:

  • select: the first listed source with a value (see mergeKcats). Sources are the names of source files (custom, ec_tree, dlkcat, okp_catapro, ...) and the BRENDA quality tiers database_exact, database_top and database_bottom, which read brenda.tsv.

  • combine: all listed sources with a value, each corrected for its bias and weighted by 1 / its error variance, both for the source's evidence for that reaction (the EC tree: measurements of the EC and its EC level; an OKP method: the enzyme's similarity to the method's training sequences). The parameters come with the BRENDA files (kcatCombineParams.tsv). model.ec.source reads 'combined (sd=, n=)'; sd is the uncertainty for a new measurement. In both, okp stands for the OKP methods of [kcat_sources.okp] methods (default: all methods with combination parameters).

The presets:

  • brenda_ec_tree (the default): custom kcats, the BRENDA median of measurements of the organism on the reaction's substrate (origin 1, without EC wildcards), the EC tree (kcatsFromECTree); then the OKP methods combined for the reactions left (without an EC number).

  • ec_tree_homologs: custom kcats, the organism's own BRENDA value; then the EC tree and homologs (kcatsFromHomologs) combined; then the OKP methods combined.

  • ec_tree_okp: custom kcats, the organism's own BRENDA value; then the EC tree, homologs and the OKP methods combined; then the OKP methods combined.

  • okp: custom kcats; then the OKP methods combined.

  • gecko_median: custom kcats, the BRENDA median of matches without EC wildcards from the organism or other organisms, with or without the substrate (origin 1 to 4), DLKcat, then the other BRENDA matches (EC wildcards, and specific activities, origin 5 and 6).

  • gecko_classic: as gecko_median with the BRENDA maximum and the specific-activity matches above DLKcat (origin up to 6), as the GECKO 3 tutorial. Against measured kcats hidden from the search, the EC tree was closer than the BRENDA median at origins 2 and 4 and with EC wildcards and as close at origins 1 and 3; the EC tree combined with the OKP methods was slightly closer than the EC tree, and the OKP methods combined as close. In ecModels, values combined with predictions set high-turnover enzymes such as ATP synthase too low, which is why the default uses predictions only where there is no value from measurements. The BRENDA aggregation is [kcat_sources.brenda] aggregation (see updateKcatSources).

After the stages:

  • custom kcats of data/customKcats.tsv are applied (applyCustomKcats), when a stage lists custom but there is no data/kcats/custom.tsv;

  • with isozymes, reactions without a kcat take one from their isozymes (getKcatAcrossIsozymes);

  • with standard, the remaining reactions get the standard kcat (getStandardKcat).

A source file a stage names that does not exist is reported and left out.

Parameters

model : struct

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

Name-Value Arguments

modelAdapter : ModelAdapter

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

writeReport : logical

write the decisions to output/_kcatDecisions.tsv (default true).

Returns

decisions : table

one row per model.ec reaction: ecRxn, stage (the stage number, or custom, isozymes, standard, or empty when no kcat was found), source (as in model.ec.source), kcat, candidates (the number of values the deciding source had for the reaction, or of sources combined), spreadLog10 (their range, in log10 units) and sdLog10 (the uncertainty of a combined value).

report : struct

  • preset: the preset used, or '' with stages;

  • missing: source files the stages name that do not exist;

  • sources: per source file loaded, its unmatched, partial and invalid rows (see loadKcatSource).

ecModel : struct

the model with the decided kcats, before applyKcatConstraints; this is what assignKcats returns, after applying the constraints.

Examples

decisions = collectKcats(ecModel);
decisions(strcmp(decisions.stage, ''), :)   % reactions without a kcat

See also

assignKcats, updateKcatSources, loadKcatSource, mergeKcats, assignKcatValues

convertCustomKcats#

function [file, report] = convertCustomKcats(model, varargin)

Convert data/customKcats.tsv into data/kcats/custom.tsv.

Writes the custom kcats of a GECKO 3 project as the curated kcat source file data/kcats/custom.tsv, which collectKcats reads first. The kcats are those applyCustomKcats gives the ecModel, including which of two entries for the same reaction wins: one row per reaction, keyed by conventional reaction and enzyme set (see getEcRxnKeys), with the entry's notes in the note column. The stoicho column is left out: complex stoichiometry comes from applyComplexData. Unlike applyCustomKcats, custom.tsv also applies to light ecModels. geckopy has the same (convert_custom_kcats).

Parameters

model : struct

the full ecModel the custom kcats are for (with EC data).

Name-Value Arguments

modelAdapter : ModelAdapter

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

customKcats : char

the file to convert (default: data/customKcats.tsv in the project).

outFile : char

the file to write (default: data/kcats/custom.tsv in the project). An existing file is not overwritten.

Returns

file : char

the file written.

report : struct

  • rows: number of rows written;

  • partial: reactions whose enzymes only partly match an entry, which applyCustomKcats does not change either (its notMatch).

Examples

convertCustomKcats(ecModel);   % then collectKcats/assignKcats read custom.tsv

See also

collectKcats, applyCustomKcats, getEcRxnKeys, upgradeGECKOproject

ecStatsFromBrenda#

function ecStats = ecStatsFromBrenda(KCATcell,SAcell)

Summarise loadBRENDAdata's output per EC number, for

reviewKcatAssignment's ecStats argument.

TODO: verify against a real BRENDA pull before relying on this. Ported from geckopy's ec_stats_from_brenda without being able to run it against real BRENDA data in this environment. In particular, loadBRENDAdata's KCATcell only carries the BRENDA max aggregate per (EC, substrate, organism) triple (column 4 of kcat.tsv) -- the median column is read internally but discarded before KCATcell is returned -- so kcatMedian below is always NaN, and reviewKcatAssignment's "ec-maximum" check (which needs a finite kcatMedian) will never fire until loadBRENDAdata is extended to also expose it.

Parameters

KCATcell : cell

as returned by loadBRENDAdata's first output: {ecCode, substrate, organism, kcatMax}.

SAcell : cell

as returned by loadBRENDAdata's second output: {ecCode, organism, kcatFromSA, mw}.

Returns

ecStats : containers.Map

EC code -> struct(nKcat,kcatMax,kcatMedian,values,nSa), keyed by the same (uppercased) EC strings BRENDA uses.

See also

reviewKcatAssignment, loadBRENDAdata

ecTreeEstimate#

function [log10kcat, n, depth, ecUsed] = ecTreeEstimate(eccodes, measurements, k)

EC-tree kcat estimates for EC numbers.

For each EC number, the median log10 kcat of its measurements is pulled toward the estimate of its parent class with weight n / (n + k), where n is the number of measurements: the global median, then the 2-digit class, the 3-digit class and the full EC number, in that order. A well-measured EC keeps its own median; a sparsely measured one leans on its class. geckopy has the same (geckopy.gather_kcats.ec_tree.ECTree).

Parameters

eccodes : cell

per query one or more EC numbers separated by ';'. The one with most measurements of its full EC is used (the first on a tie).

measurements : struct

BRENDA measurement table with fields ec and log10kcat (see loadBrendaMeasurements).

k : double

shrinkage constant (default 5): the number of measurements at which an EC's own median and its class count equally.

Returns

log10kcat : double

the estimates; the global median for queries without measurements.

n : double

number of measurements of the full EC number used.

depth : double

deepest EC level with measurements: 4, 3, 2, or 0 when there are none (or no EC number).

ecUsed : cell

the EC number used.

Examples

m = loadBrendaMeasurements();
[v, n, depth] = ecTreeEstimate({'1.1.1.1'; '2.7.1.1;2.7.1.2'}, m);
kcat = 10.^v;

See also

kcatsFromECTree, loadBrendaMeasurements

extractEnzymeSubstratePairs#

function pairs = extractEnzymeSubstratePairs(model, varargin)

The enzyme-substrate pairs of an ecModel's reactions.

Lists, for each model.ec reaction, its enzymes and its substrates as DLKcat and the homolog search use them: the reactants of the reaction, without the metabolites of DLKcatIgnoreMets.tsv (metal ions, small molecules), without protein pseudometabolites, and without currency metabolites of DLKcatCurrencyMets.tsv where both members of a pair take part (unless no other substrate remains). Both files are read from the data folder of the project, or else from the databases folder of GECKO. geckopy has the same (extract_enzyme_substrate_pairs).

Parameters

model : struct

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

Name-Value Arguments

ecRxns : logical

which model.ec.rxns to list (default: all).

modelAdapter : ModelAdapter

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

Returns

pairs : struct

ecRxn (index into model.ec.rxns), protein (index into model.ec.genes, model.ec.enzymes and model.ec.sequence) and met (index into model.mets), one entry per pair, reaction by reaction.

Examples

pairs = extractEnzymeSubstratePairs(ecModel);
model.metNames(pairs.met(1:5))

See also

writeDLKcatInput, kcatsFromHomologs

fetchOpenKineticsPredictor#

function [done, kcatList] = fetchOpenKineticsPredictor(model, varargin)

Fetch and parse an OpenKineticsPredictor job.

Checks the status of an OpenKineticsPredictor job and, when it has finished, downloads the result to data/OKP_output.csv and parses it (via readOpenKineticsPredictorOutput) into a kcatList consumable by assignKcatValues.

The API key (only needed when useStored=false) is resolved from the OKP_API_KEY environment variable or data/okpApiKey.txt; see submitOpenKineticsPredictor for how to obtain and store a key.

Parameters

model : struct

ecModel in GECKO 3 format (with ecModel.ec structure; model.metSmiles is required to map results back).

Name-Value Arguments

useStored : logical

if true, skip the API entirely and parse the already-downloaded data/OKP_output.csv. If false, query the API (default false).

jobId : char

OKP job id (default: read from data/OKP_job.txt, written by submitOpenKineticsPredictor).

wait : logical

if true, poll until the job finishes; if false, report once and return (default false).

pollInterval : double

seconds between polls when wait=true (default 30).

outFile : char

where the result is stored, and read from with useStored=true (default: data/OKP_output.csv).

modelAdapter : ModelAdapter

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

Returns

done : logical

true if a result was obtained (downloaded or loaded from disk).

kcatList : struct

structure with kcat values (empty when not done); see readOpenKineticsPredictorOutput for its fields (source, rxns, genes, substrates, kcats, kcatSource).

Examples

[done, kcatList] = fetchOpenKineticsPredictor(model);                        % check once
[done, kcatList] = fetchOpenKineticsPredictor(model, 'wait', true);          % poll
[done, kcatList] = fetchOpenKineticsPredictor(model, 'useStored', true);     % parse stored file

See also

submitOpenKineticsPredictor, readOpenKineticsPredictorOutput

fuzzyKcatMatching#

function kcatList = fuzzyKcatMatching(model, varargin)

Match model EC numbers and substrates to BRENDA kcats.

Matches the model EC numbers and substrates to the BRENDA database, to return the corresponding kcats for each reaction. If no exact match is found, less specific kcat values are found from (a) evolutionary closely related organism; (b) different substrate; (c) calculated from specific activities; (d) wildcards in the EC number. The model organism is provided in the model adapter as obj.params.org_name, and evolutionary distance to other organisms is determined via KEGG phylogeny. If an organism name occurs multiple times in KEGG, the first instance will be used when determining evolutionary distance.

Parameters

model : struct

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

Name-Value Arguments

ecRxns : logical

for which reactions (from model.ec.rxns) kcat values should be found, provided as logical vector with same length as model.ec.rxns (default: all reactions).

modelAdapter : ModelAdapter

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

forceWClvl : double

force a minimum wildcard level (default 0).

Returns

kcatList : struct

structure array with list of BRENDA derived kcat values, with separate entries for each kcat value.

Notes

The kcatList structure has the following fields:

  • source : 'brenda'.

  • rxns : reaction identifiers.

  • substrates : substrate names.

  • kcats : proposed kcat value in /sec.

  • eccodes : as used to query BRENDA.

  • wildcardLvl : which level of EC wild-card was necessary to find a match (0: w.x.y.z; 1: w.x.y.-; 2: w.x.-.-; 3: w.-.-.-).

  • origin : which level of specificity was necessary to find a match (1: correct organism, correct substrate, kcat; 2: any organism, correct substrate, kcat; 3: correct organism, any substrate, kcat; 4: any organism, any substrate, kcat; 5: correct organism, specific activity; 6: any organism, specific activity). Levels are tried in the order 1, 2, 3, 5, 4, 6: a specific activity from the correct organism is preferred over a kcat from any organism with any substrate. When a reaction has multiple EC numbers, the EC with the fewest wildcards and the earliest-tried level is selected, and among those the highest kcat.

If a wildcard is used, origin levels 1 and 2 are ignored. The last digits in the E.C. number indicate the substrate specificity, so if this should be ignored, then correct substrate matches should not be prioritized.

Examples

% optional arguments may be given positionally or as name-value pairs:
kcatList = fuzzyKcatMatching(model);
kcatList = fuzzyKcatMatching(model, 'forceWClvl', 1);

See also

mergeDLKcatAndFuzzyKcats, assignKcatValues

getEcRxnKeys#

function [baseRxns, enzymeSets] = getEcRxnKeys(model)

Build-independent keys of the model.ec reactions.

A kcat source file (see saveKcatSource) identifies a reaction by its conventional reaction and its enzyme set, not by model.ec.rxns, whose identifiers depend on how the ecModel was built. This function gives both keys for every model.ec row.

Parameters

model : struct

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

Returns

baseRxns : cell

per model.ec.rxns entry, the conventional reaction: without a trailing EXP (full model) or a leading _ (light model). A reverse direction keeps its _REV.

enzymeSets : cell

per model.ec.rxns entry, the UniProt accessions of its enzymes (model.ec.rxnEnzMat), sorted and joined by ' + '; empty without enzymes.

Examples

[baseRxns, enzymeSets] = getEcRxnKeys(ecModel);

See also

saveKcatSource, loadKcatSource

getStandardKcat#

function [model, rxnsMissingGPR, standardMW, standardKcat, rxnsNoKcat] = getStandardKcat(model, varargin)

Assign standard kcat and MW to reactions without enzymes.

Calculates a standard kcat and standard molecular weight (MW) that can be used to apply enzyme constraints to reactions without any associated enzymes. Such reactions have either an empty model.grRules field, or they have no match in model.ec.rxns (which can be the case if the genes in the model.grRules field could not be mapped to enzymes). This is done by adding those reactions to model.ec, assigning a "standard" pseudoenzyme with the standard MW (median of all proteins in the organism) and standard kcat (median from all kcat, or subsystem specific kcat).

A reaction is assigned a subSystem specific kcat value if the model has a subSystems field and the reaction is annotated with a subSystem. Only the first subSystem will be considered if multiple are annotated to the same reaction.

Exchange, transport and pseudoreactions are filtered out, plus any reaction identifiers specified in /data/pseudoRxns.tsv in the model adapter folder.

In addition, reactions that are annotated with an enzyme (and therefore already in model.ec), but not assigned any reaction-specific kcat value (their model.ec.kcat entry is either 0 or NaN), can be assigned standard kcat values by a similar approach. However, those reactions will not be linked to the "standard" pseudoenzyme, but will use the enzyme that they had already been associated with.

Any pre-existing standard kcat assignments (identified by 'standard' entries in model.ec.source) are removed when applying this function.

Parameters

model : struct

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

Name-Value Arguments

modelAdapter : ModelAdapter

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

threshold : double

a threshold to determine whether to use a kcat value based on the median kcat of the reactions in the same subSystem or based on the median value of all the kcat in the model. The second option is used when the number of reactions in a determined subSystem with a real (nonzero, non-NaN) kcat value is < threshold (default 10).

fillZeroKcat : logical

whether zero kcat values should be replaced with standard kcat values (default true).

Returns

model : struct

ecModel where model.ec is expanded with a standard protein with standard kcat and standard MW, assigned to reactions without gene associations.

rxnsMissingGPR : cell

a list of updated rxns identifiers with a standard value.

standardMW : double

the standard MW value calculated.

standardKcat : double

the standard kcat value calculated.

rxnsNoKcat : cell

a list of rxns identifiers whose zero kcat has been replaced.

Notes

While model.ec.kcat is populated, applyKcatConstraints would still need to be run to apply the new constraints to the S-matrix.

Examples

% optional arguments may be given positionally or as name-value pairs:
[model, rxnsMissingGPR, standardMW, standardKcat, rxnsNoKcat] = getStandardKcat(model);
[model, rxnsMissingGPR, standardMW, standardKcat, rxnsNoKcat] = getStandardKcat(model, 'threshold', 20);

See also

removeStandardKcat, applyKcatConstraints

kcatAssignmentConfig#

function config = kcatAssignmentConfig(params)

The kcat assignment settings of a model adapter.

Reads [kcat_assignment] and [kcat_sources.*] of model_adapter.toml (or params.kcat_assignment and params.kcat_sources of an adapter class), and expands a preset into its stages, as collectKcats and updateKcatSources use them. Without a preset or stages the preset is brenda_ec_tree. geckopy's kcat_assignment_config gives the same settings.

Parameters

params : struct

the parameters of a model adapter (modelAdapter.params).

Returns

config : struct

  • preset: the preset name, or '' when stages are given;

  • isozymes, standard: logical;

  • stages: struct array with action ('select' or 'combine'), sources (cell, as given), files (the source files they read, with okp replaced by the files of its methods), criteria, topOriginLimit, bottomOriginLimit and wildcardLimit;

  • okpMethods: the OKP methods of the okp source group ([kcat_sources.okp] methods; default all methods with combination parameters);

  • sources: per source name its options (from [kcat_sources] and the preset).

Examples

config = kcatAssignmentConfig(modelAdapter.params);
config.stages(1).sources   % the order of the sources

See also

collectKcats, assignKcats, updateKcatSources

kcatsFromBrenda#

function kcatList = kcatsFromBrenda(model, varargin)

Gather kcats from BRENDA and keep them as a source file.

Matches the model's EC numbers and substrates to BRENDA by fuzzy matching (see fuzzyKcatMatching), and writes the result to data/kcats/brenda.tsv in the project folder (see saveKcatSource). The matching runs locally on the BRENDA files of GECKO.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure), with EC numbers (getECfromDatabase or getECfromGEM).

Name-Value Arguments

aggregation : char

which BRENDA value per EC number, substrate and organism is used: 'max' or 'median' (default: params.kcatAggregation of the model adapter, or 'max').

forceWClvl : double

force a minimum wildcard level in the EC numbers (default 0).

ecRxns : logical

for which model.ec.rxns kcats are gathered (default: all).

save : logical

write the source file (default true).

saveAs : char

name of the source file, without .tsv (default 'brenda'). With ecRxns, the file then only holds those reactions.

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

the kcat values, as returned by fuzzyKcatMatching.

Examples

kcatsFromBrenda(ecModel);
kcatList = kcatsFromBrenda(ecModel, 'aggregation', 'median');

See also

fuzzyKcatMatching, kcatsFromDLKcat, kcatsFromOKP, saveKcatSource, loadKcatSource

kcatsFromDLKcat#

function kcatList = kcatsFromDLKcat(model, varargin)

Gather kcats from DLKcat and keep them as a source file.

Predicts kcats with DLKcat and writes them to data/kcats/dlkcat.tsv in the project folder (see saveKcatSource). With 'run', true it writes the DLKcat input (writeDLKcatInput) and runs DLKcat through its Docker image (runDLKcat), which needs Docker; otherwise it reads the output of an earlier run (readDLKcatOutput). A run records how many reactions it covered in data/DLKcat_run.txt, so that the source file says so also when the output is read later.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure), with metabolite SMILES (findMetSmiles) and protein sequences.

Name-Value Arguments

run : logical

write the input and run DLKcat; false reads the existing output in data/DLKcat.tsv (default false).

ecRxns : logical

for which model.ec.rxns DLKcat is run (default: all). Only used with 'run', true.

save : logical

write the source file (default true).

saveAs : char

name of the source file, without .tsv (default 'dlkcat').

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

the kcat values, as returned by readDLKcatOutput.

Examples

kcatsFromDLKcat(ecModel, 'run', true);
kcatList = kcatsFromDLKcat(ecModel);

See also

writeDLKcatInput, runDLKcat, readDLKcatOutput, kcatsFromBrenda, saveKcatSource

kcatsFromECTree#

function kcatList = kcatsFromECTree(model, varargin)

Estimate kcats from the EC tree and keep them as a source file.

Each reaction gets the median kcat of all wild-type BRENDA measurements of its EC number, from any organism and substrate, shrunk toward the median of the EC's 3-digit and 2-digit classes with weight n / (n + k) for n measurements (see ecTreeEstimate). A reaction with several EC numbers uses the one with most measurements. Reactions without an EC number, or whose EC classes have no measurements, get no value. The result is written to data/kcats/ec_tree.tsv in the project folder (see saveKcatSource).

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure), with EC numbers (getECfromDatabase or getECfromGEM).

Name-Value Arguments

k : double

shrinkage constant (default 5): the number of measurements at which an EC's own median and its class count equally.

ecRxns : logical

for which model.ec.rxns kcats are estimated (default: all).

measurements : struct

BRENDA measurement table (default: loadBrendaMeasurements with the model adapter).

save : logical

write the source file (default true).

saveAs : char

name of the source file, without .tsv (default 'ec_tree'). With ecRxns, the file then only holds those reactions.

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

the kcat values, with fields source, rxns, eccodes, kcats and detail (the number of measurements of the EC, n, and the deepest EC level with measurements, depth).

Examples

kcatsFromECTree(ecModel);
kcatList = kcatsFromECTree(ecModel, 'k', 10, 'save', false);

See also

ecTreeEstimate, loadBrendaMeasurements, kcatsFromBrenda, saveKcatSource, assignKcats

kcatsFromHomologs#

function kcatList = kcatsFromHomologs(model, varargin)

Estimate kcats from measured homologs and keep them as a source file.

For each reaction, enzyme and substrate (the substrates DLKcat would use, see extractEnzymeSubstratePairs), the enzyme's sequence is searched with DIAMOND against the sequences of the BRENDA measurements (at least 40% identity, 80% coverage of both sequences). Each homolog measured on the same substrate (same InChIKey, without the protonation flag) contributes the median of its measurements; the estimate is the mean of the k most identical such homologs, weighted by identity. Homologs at 95% identity or more are measurements of (nearly) the same protein: when there are any, the estimate is the median of those alone. For an enzyme complex the estimate is the median over its subunits. Model metabolites are matched to InChIKeys through substrates.tsv of the BRENDA files: their ChEBI annotations, then MetaNetX annotations (model.metMiriams), then their names. Reactions without a homolog measured on one of their substrates get no value. The result is written to data/kcats/homologs.tsv (see saveKcatSource). DIAMOND is RAVEN's (getDiamond; downloaded when missing). geckopy has the same (kcats_from_homologs).

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure), with enzyme sequences (model.ec.sequence).

Name-Value Arguments

k : double

the number of most identical homologs averaged (default 10).

minIdentity : double

DIAMOND identity threshold, as a fraction (default 0.4).

coverage : double

DIAMOND coverage threshold of both sequences, as a fraction (default 0.8).

threads : double

DIAMOND threads (default: DIAMOND's).

save : logical

write the source file (default true).

saveAs : char

name of the source file, without .tsv (default 'homologs').

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

the kcat values, with fields source, rxns, substrates, kcats and detail (the identity of the nearest homolog, identity, and the number of homologs used, n).

Examples

kcatsFromHomologs(ecModel);

See also

kcatsFromECTree, extractEnzymeSubstratePairs, saveKcatSource, collectKcats

kcatsFromOKP#

function [kcatList, done] = kcatsFromOKP(model, varargin)

Gather kcats from OpenKineticsPredictor and keep them as a source file.

Predicts kcats with one OpenKineticsPredictor (OKP) method and writes them to data/kcats/okp_.tsv in the project folder (see saveKcatSource). OKP is a web service with a job queue, so this function can be called repeatedly:

  • without a job for this method, it submits one (submitOpenKineticsPredictor);

  • with a job, it fetches the result (fetchOpenKineticsPredictor). When the job is done the file is written; otherwise it reports the job's status and writes nothing.

Each method keeps its own job in data/OKP_job_.txt and its own result in data/OKP_output_.csv, so jobs of several methods can run at the same time. The job file records which job the stored result came from; useStored only uses a result of the current job. An API key is needed (see resolveOkpApiKey).

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure), with metabolite SMILES (findMetSmiles) and protein sequences.

Name-Value Arguments

method : char

OKP method, e.g. 'CataPro', 'CatPred', 'CatRange', 'DLKcat', 'EITLEM', 'KinForm-H', 'KinForm-L', 'OmniESI', 'TurNup', 'UniKP' (default: params.okp.method of the model adapter, or 'CataPro').

wait : logical

wait until the job is done (default false).

resubmit : logical

submit a new job even if one exists for this method; its earlier result is removed (default false).

useStored : logical

read the stored result of this method's job, without contacting OKP (default false).

ecRxns : logical

for which model.ec.rxns kcats are predicted (default: all). Only used when a job is submitted.

save : logical

write the source file (default true).

saveAs : char

name of the source file, without .tsv (default 'okp_', in lower case, with other characters than letters and digits as '_').

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

the kcat values, as returned by readOpenKineticsPredictorOutput; empty while the job is not done.

done : logical

whether the result was available.

Examples

kcatsFromOKP(ecModel, 'method', 'CataPro');          % submits
kcatsFromOKP(ecModel, 'method', 'CataPro');          % later: fetches and writes
kcatsFromOKP(ecModel, 'method', 'UniKP', 'wait', true);

See also

submitOpenKineticsPredictor, fetchOpenKineticsPredictor, kcatsFromBrenda, saveKcatSource

loadBrendaMeasurements#

function measurements = loadBrendaMeasurements(varargin)

Load the BRENDA measurement table.

Reads measurements.tsv from the BRENDA database folder of the model adapter (next to kcat.tsv, sa.tsv and mw.tsv): one row per wild-type BRENDA kcat with an EC number, after the outlier screen, with the substrate, organism, UniProt accession and sequence id of each measurement. geckopy reads the same file (load_brenda_measurements).

Name-Value Arguments

modelAdapter : ModelAdapter

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

folder : char

folder with measurements.tsv, instead of the adapter's BRENDA folder.

Returns

measurements : struct

one field per column of the file (ec, substrate, substrate_inchikey, organism, taxid, uniprot, seq_id, temperature, ph and pmid as cell arrays of char; kcat as double), plus log10kcat and release (the release line of the file, e.g. 'BRENDA release 2026.1').

Examples

measurements = loadBrendaMeasurements();

See also

kcatsFromECTree, ecTreeEstimate, loadBRENDAdata

loadKcatSource#

function [kcatList, report] = loadKcatSource(model, name, varargin)

Read a kcat source file and map its rows to an ecModel.

Reads data/kcats/.tsv (see saveKcatSource) and maps every row to the model.ec reactions it applies to, by conventional reaction and enzyme set (see getEcRxnKeys):

  1. A row with rxn and enzymes applies to the model.ec rows with that conventional reaction and that enzyme set.

  2. A row with only enzymes applies to every model.ec row with that enzyme set; a row with only rxn to every model.ec row of that conventional reaction (curated rows; saveKcatSource always writes both).

  3. A row whose kcat is missing, not a number, infinite, or not above 0 is reported as invalid and not applied.

  4. A row that matches nothing is reported, never dropped silently. If a model.ec row has at least half of the row's enzymes, that partial match is reported as well, but not applied.

The enzymes of a row may be listed in any order.

The file is read as UTF-8 (a leading byte-order mark is ignored). The '#' lines before the column header are the header; '#' lines and blank lines further down are skipped. Fields wrapped in double quotes, as a spreadsheet may save them, are unwrapped. kcat and log10_sd must be plain numbers (12, 0.5, 1e-05); other text, such as '5,5' with a decimal comma, is reported as invalid. A row with more filled fields than there are columns is an error.

Parameters

model : struct

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

name : char

name of the source (data/kcats/.tsv in the project folder), or the path to a kcat source file.

Name-Value Arguments

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

kcat values per model.ec reaction, as used by mergeKcats and assignKcatValues: source (the source name), rxns, kcats, substrates, eccodes, wildcardLvl and origin (from the detail column), kcatSource (the per-row source), log10sd, detail (the detail column), and line (the line of the file each entry comes from).

report : struct

  • invalid: table of the file rows with a missing or invalid kcat;

  • unmatched: table of the file rows that apply to no model.ec row;

  • partial: table of rows that only partly match an enzyme set, with the model.ec reaction and its enzymes;

  • header: the '#' header lines of the file, as field: value (for instance header.source, header.parameters);

  • records: the rows of the file as read, one field per column (kcat and log10_sd as double, other columns as cell of char) and line, the line number of each row.

Examples

kcatList = loadKcatSource(ecModel, 'brenda');
[kcatList, report] = loadKcatSource(ecModel, 'custom');

See also

saveKcatSource, kcatsFromBrenda, getEcRxnKeys

mergeDLKcatAndFuzzyKcats#

function mergedKcatList = mergeDLKcatAndFuzzyKcats(kcatListDLKcat, kcatListFuzzy, varargin)

Merge DLKcat and BRENDA fuzzy matching results.

Deprecated thin wrapper around mergeKcats, kept for the common DLKcat + fuzzy-BRENDA case. New code should call mergeKcats directly, which also handles a single list that mixes several sources (e.g. an OpenKineticsPredictor result with BRENDA/Sabio-RK/CataPro rows).

Merges the results from DLKcat and fuzzy matching to the BRENDA database. Order of preference:

  1. BRENDA match with correct E.C. number, with origin (see below) not lower than the specified topOriginLimit.

  2. DLKcat match.

  3. BRENDA match with correct E.C. number, with origin below topOriginLimit but not lower than the bottomOriginLimit.

  4. BRENDA match with wildcards in the E.C. number, with not more wildcards than wildcardLimit, and origin not lower than the bottomOriginLimit.

Parameters

kcatListDLKcat : struct

kcatList derived from readDLKcatOutput.

kcatListFuzzy : struct

kcatList derived from fuzzyKcatMatching.

Name-Value Arguments

topOriginLimit : double

origin limit for prioritized BRENDA matches. Origin is explained in more detail below (default 6).

bottomOriginLimit : double

origin limit for low priority BRENDA matches. Origin is explained in more detail below (default 6).

wildcardLimit : double

maximum number of wildcards in E.C. number of BRENDA matches (default 3).

Returns

mergedKcatList : struct

merged kcatList with the same field layout produced by mergeKcats (source, kcatSource, rxns, genes, substrates, kcats, eccodes, wildcardLvl, origin), keeping only the rows selected by the order of preference above.

Notes

The origin parameter:

  • 1 : correct organism, correct substrate, kcat.

  • 2 : any organism, correct substrate, kcat.

  • 3 : correct organism, any substrate, kcat.

  • 4 : any organism, any substrate, kcat.

  • 5 : correct organism, specific activity.

  • 6 : any organism, specific activity.

Example of wildcards in E.C. number:

  • 0 : 1.1.1.3 glycerol-3-phosphate dehydrogenase (NAD+).

  • 1 : 1.1.1.- oxidoreductase, acting on the CH-OH group of donors, with NAD+ or NADP+ as acceptor.

  • 2 : 1.1.-.- oxidoreductase, acting on the CH-OH group of donors.

  • 3 : 1.-.-.- oxidoreductase.

Examples

% optional arguments may be given positionally or as name-value pairs:
mergedKcatList = mergeDLKcatAndFuzzyKcats(kcatListDLKcat, kcatListFuzzy);
mergedKcatList = mergeDLKcatAndFuzzyKcats(kcatListDLKcat, kcatListFuzzy, 'wildcardLimit', 2);

See also

mergeKcats, readDLKcatOutput, fuzzyKcatMatching, assignKcatValues

mergeKcats#

function mergedKcatList = mergeKcats(kcatLists, sourcePriority, varargin)

Merge any number of kcatLists, keeping the highest-priority

source for each reaction.

Generalizes mergeDLKcatAndFuzzyKcats: instead of two fixed inputs (DLKcat

  • fuzzy BRENDA) it accepts a cell array of kcatLists, each of which may itself mix several sources (for example the output of fetchOpenKineticsPredictor, carrying BRENDA, Sabio-RK and CataPro values in its kcatSource field). A caller-supplied sourcePriority decides which source wins for each reaction.

Parameters

kcatLists : cell

cell array of kcatList structs (as produced by fuzzyKcatMatching, readDLKcatOutput, fetchOpenKineticsPredictor, ...).

sourcePriority : cell

cell array of tier tokens / source labels, best first. Three reserved tier tokens may be used instead of a literal source label:

  • 'database_exact' an exact experimental-database measurement (a BRENDA/Sabio-RK row with no fuzzy metadata, i.e. a direct OKP hit, no wildcards).

  • 'database_top' a fuzzy BRENDA match with wildcardLvl==0 and origin<=topOriginLimit.

  • 'database_bottom' weaker fuzzy BRENDA matches within wildcardLimit / bottomOriginLimit.

Any other token is matched against each row's source after folding to lowercase snake_case (e.g. 'dlkcat', 'catapro'). Sources not listed are dropped.

Name-Value Arguments

topOriginLimit : double

origin limit for database_top (default 6).

bottomOriginLimit : double

origin limit for database_bottom (default 6).

wildcardLimit : double

maximum wildcards for database_bottom's wildcard branch (default 3).

databaseSources : cell

source labels treated as experimental databases, i.e. routed to the database_* tiers (default {'brenda','sabio_rk'}).

Returns

mergedKcatList : struct

merged kcatList, keeping only the winning rows per reaction; see Notes below for its fields. Row order follows the order of the input lists (each list's surviving rows, in turn), so a two-list call behaves like the legacy mergeDLKcatAndFuzzyKcats.

Notes

The mergedKcatList structure has the following fields:

  • source : 'merged'.

  • kcatSource : per-row provenance, preserved verbatim from the input lists.

  • rxns : reaction identifiers.

  • genes : gene identifiers (where provided by the input lists).

  • substrates : substrate names (where provided by the input lists).

  • kcats : selected kcat value in /sec.

  • eccodes : as used to query BRENDA (where applicable).

  • wildcardLvl : wildcard level of the source match (where applicable).

  • origin : specificity level of the source match (where applicable).

The origin parameter:

  • 1 : correct organism, correct substrate, kcat.

  • 2 : any organism, correct substrate, kcat.

  • 3 : correct organism, any substrate, kcat.

  • 4 : any organism, any substrate, kcat.

  • 5 : correct organism, specific activity.

  • 6 : any organism, specific activity.

Examples

% optional arguments may be given positionally or as name-value pairs:
mergedKcatList = mergeKcats({kcatListFuzzy, kcatListDLKcat}, ...
    {'database_top', 'dlkcat', 'database_bottom'});
mergedKcatList = mergeKcats({kcatListFuzzy, kcatListOKP}, ...
    {'database_exact', 'database_top', 'database_bottom'}, 'wildcardLimit', 2);

See also

mergeDLKcatAndFuzzyKcats, readDLKcatOutput, fuzzyKcatMatching, assignKcatValues

readDLKcatOutput#

function kcatList = readDLKcatOutput(model, varargin)

Read the DLKcat output file into a kcatList structure.

Reads the DLKcat output file and constructs a kcatList structure, that can be used by assignKcatValues() to populate the ecModel with kcat values.

Parameters

model : struct

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

Name-Value Arguments

outFile : char

name and path of the DLKcat output file (default: data/DLKcat.tsv from the obj.params.path folder specified in the modelAdapter).

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

structure array with list of DLKcat derived kcat values, with separate entries for each kcat value.

Notes

The kcatList structure has the following fields:

  • source : 'DLKcat'.

  • rxns : reaction identifiers.

  • genes : gene identifiers.

  • substrates : substrate names.

  • kcats : predicted kcat value in /sec.

Examples

% optional arguments may be given positionally or as name-value pairs:
kcatList = readDLKcatOutput(model);
kcatList = readDLKcatOutput(model, 'outFile', 'myDLKcat.tsv');

See also

runDLKcat, writeDLKcatInput, assignKcatValues

readOpenKineticsPredictorOutput#

function kcatList = readOpenKineticsPredictorOutput(model, varargin)

Read OpenKineticsPredictor output to kcatList.

Reads the OpenKineticsPredictor output file (job-*-output.csv with columns: kcat (1/s), Source kcat, Extra Info kcat, Protein Sequence, Substrate) and constructs a kcatList structure, that can be used by assignKcatValues() to populate the ecModel with kcat values.

CatRange predicts a class of kcat values, which OKP returns as its range (for instance '10 to 100 s^-1'). It is read as the geometric midpoint of the range, or half the upper bound for the class starting at 0.

The per-entry Source kcat column (e.g. 'Prediction from CatPred', 'BRENDA', 'Sabio-RK', 'UniProt') is preserved in kcatList.kcatSource so that assignKcatValues() records the actual provenance of each value.

Parameters

model : struct

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

Name-Value Arguments

outFile : char

name and path of the OpenKineticsPredictor output CSV. If omitted, a file selection dialog is opened, starting in the data/ folder specified by the modelAdapter.

modelAdapter : ModelAdapter

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

Returns

kcatList : struct

structure array with list of kcat values from OpenKineticsPredictor, with separate entries for each kcat value.

Notes

The kcatList structure has the following fields:

  • source : 'OpenKineticsPredictor'.

  • rxns : reaction identifiers, matching model.ec.rxns.

  • genes : gene identifiers, matching model.ec.genes.

  • substrates : substrate names, matching model.metNames.

  • kcats : kcat values in /sec.

  • similarity : the enzyme's highest sequence similarity to the method's training data, in percent (NaN without the similarity column)

  • kcatSource : per-entry source as reported by OKP, prefixed with 'OKP-' (e.g. 'OKP-CatPred', 'OKP-BRENDA', 'OKP-Sabio-RK', 'OKP-UniProt').

Examples

% optional arguments may be given positionally or as name-value pairs:
kcatList = readOpenKineticsPredictorOutput(model);
kcatList = readOpenKineticsPredictorOutput(model, 'outFile', 'job-output.csv');

See also

writeOpenKineticsPredictorInput, assignKcatValues

removeStandardKcat#

function model = removeStandardKcat(model)

Remove the standard pseudoenzyme and standard kcats.

Removes the "standard" pseudoenzyme and standard kcat and MW values, as they were introduced by getStandardKcat. Also standard kcat values that were assigned by getStandardKcat if fillZeroKcat was set to true are removed from model.ec.kcat. Both the model.ec and model.S structures are modified.

Parameters

model : struct

an ecModel in GECKO 3 format (with ecModel.ec structure) that has standard kcat values implemented by getStandardKcat.

Returns

model : struct

ecModel without standard pseudoprotein and standard kcat values.

Examples

model = removeStandardKcat(model);

See also

getStandardKcat, applyKcatConstraints

resolveOkpApiKey#

function key = resolveOkpApiKey(argKey, basePath)

Resolve the OpenKineticsPredictor API key.

Internal helper shared by submitOpenKineticsPredictor and fetchOpenKineticsPredictor; not intended to be called directly.

Checked in order: the argKey input, the OKP_API_KEY environment variable, then a plain-text file data/okpApiKey.txt under basePath (this name is git-ignored by GECKO). The key is a secret and must never be read from the model adapter, which is shared/committed.

Parameters

argKey : char

an explicitly provided key, or empty to fall through to the environment variable / file.

basePath : char

the model adapter's params.path, under which data/okpApiKey.txt is looked up.

Returns

key : char

the resolved API key.

See also

submitOpenKineticsPredictor, fetchOpenKineticsPredictor

reviewKcatAssignment#

function findings = reviewKcatAssignment(rxnIds,kcats,sources,ecCodes,varargin)

Flag kcat assignments that deserve a second look.

A tuner's largest corrections are rarely discoveries about biology. They are places the assignment went wrong: a value derived from one specific-activity measurement, a database maximum standing in for a distribution with a two-hundred-fold spread, one fallback number reused across a whole family of reactions. Finding those directly is cheaper than inferring them from a fit, and a corrected prior propagates to every model built from the same databases, where a tuned kcat stays in the model it was tuned on.

Two design choices, both from measurement rather than taste (see geckopy's gather_kcats/review.py, which this ports):

Rank by leverage, and cut the report there. Tightening the checks themselves does not shorten a report nearly as well, because looking odd and mattering are unrelated properties. Filtering by leverage keeps the list short and keeps the entries worth a curator's time.

Report a parameter once. Isozyme copies the assignment could not separate share a value and a source, so they share a finding; listing them separately fills the report with duplicates of one decision.

Parameters

rxnIds, kcats, sources, ecCodes : cell/double

ec.rxns, ec.kcat, ec.source, ec.eccodes (or the equivalent subset), all the same length.

Name-Value Arguments

ecStats : containers.Map

EC code -> struct(nKcat,kcatMax,kcatMedian,values,nSa), as returned by ecStatsFromBrenda. Checks needing it are skipped when it is absent, so this still runs without a database.

enzymes : cell

protein ids per kcat (cell of cell arrays), used to count how many other reactions share an enzyme.

names : cell

reaction names, same length as rxnIds (default: not shown).

leverage : double

per-kcat effect on the distance from a one-at-a-time screen (e.g. screenKcatLeverage's leverage column, expanded back to ecModel.ec.rxns positions). Without it findings cannot be ranked and are returned in input order.

slow, fast : double

magnitude check bounds (default 1e-2, 1e4).

ecMaxGap : double

how many times the EC median a value must exceed, while sitting exactly at the EC max, to flag as ec-maximum (default 3.0).

repeatMin : double

how many distinct reactions must share one kcat value to flag as repeated-value (default 5).

include : cell

names from {'standard-fallback','tied-isozymes'} to report as well (default: neither -- both are deliberate choices, not mistakes, so stay quiet unless asked for).

coverage : double

truncate the report to the rows carrying this share of the flagged leverage (default: no truncation).

top : double

truncate the report to this many rows (default: no truncation).

Returns

findings : table

one row per free parameter: rxnId, name, ecCode, source, kcat, leverage, nIsozymes, otherReactions, checks (comma-joined string), detail. Write to TSV with e.g. writetable(findings,'findings.tsv','FileType','text','Delimiter','\t')

See also

ecStatsFromBrenda, isozymeTieMap, screenKcatLeverage

runDLKcat#

function runDLKcat(varargin)

Run DLKcat to predict kcat values from a Docker image.

Runs DLKcat via a Docker image; once it completes successfully, the DLKcat file is overwritten with the predicted output, in the model- specific 'data' sub-folder taken from modelAdapter (e.g. GECKO/tutorials/tutorial_yeast-GEM/data/DLKcat.tsv).

Name-Value Arguments

modelAdapter : ModelAdapter

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

filePath : char

path to the DLKcat.tsv file (default: data/DLKcat.tsv).

Notes

  1. Requires Docker to be installed, and Docker Desktop running. Visit "https://www.docker.com".

  2. Runtime will depend on whether the image is to be downloaded or not.

See also

writeDLKcatInput, readDLKcatOutput

saveKcatSource#

function filename = saveKcatSource(model, kcatList, name, varargin)

Write a kcatList to a kcat source file of the project.

Writes the kcat values of kcatList to data/kcats/.tsv in the project folder, the file that loadKcatSource reads back. Rows are keyed by their conventional reaction and enzyme set (see getEcRxnKeys), not by model.ec.rxns, so the file stays valid when the ecModel is rebuilt. kcatsFromBrenda, kcatsFromDLKcat and kcatsFromOKP write these files for their sources; use this function for a kcatList made in another way.

The file is UTF-8 text. It starts with '#' header lines (source, generator, parameters, data, kind, created), then a tab-separated table with the columns rxn, enzymes, substrate, kcat, log10_sd, source, detail, ec_code and note, sorted by all columns from rxn onwards. Left out are:

  • rows whose kcat is not a positive finite number (0 means no value was found);

  • rows of model.ec reactions without enzymes, which have no enzyme constraint and could not be told apart from their isozymes.

Parameters

model : struct

the ecModel the kcatList refers to.

kcatList : struct

kcat values as returned by kcatsFromBrenda, fuzzyKcatMatching, readDLKcatOutput, readOpenKineticsPredictorOutput or mergeKcats: fields rxns and kcats, optionally source, substrates, eccodes, wildcardLvl, origin, kcatSource, log10sd and detail (further key=value pairs for the detail column).

name : char

name of the source; the file is .tsv.

Name-Value Arguments

modelAdapter : ModelAdapter

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

folder : char

folder to write to (default: data/kcats in the project folder).

generator : char

what produced the values (default: 'saveKcatSource').

parameters : struct

settings used to produce the values, written as compact JSON with sorted keys (default: none).

data : char

version of the data the values come from, e.g. a BRENDA release (default: empty).

kind : char

'gathered' (default) or 'curated'.

A file whose header says 'kind: curated' or 'source: custom', or named :

custom.tsv, is never written. :

Returns

filename : char

the file written.

Examples

kcatList = fuzzyKcatMatching(ecModel);
saveKcatSource(ecModel, kcatList, 'mybrenda');

See also

kcatsFromBrenda, loadKcatSource, getEcRxnKeys

submitOpenKineticsPredictor#

function jobId = submitOpenKineticsPredictor(model, varargin)

Submit a kcat prediction job to OpenKineticsPredictor.

Builds the OpenKineticsPredictor input (protein sequences + single-substrate SMILES, via writeOpenKineticsPredictorInput) and submits a kcat prediction job to the OKP REST API (https://predictor.openkinetics.org/). The returned job id is also stored in data/OKP_job.txt, so fetchOpenKineticsPredictor can pick it up later.

Predictors available via OKP: CataPro, CatPred, CatRange, DLKcat, EITLEM, KinForm-H, KinForm-L, OmniESI, OmniESI-O2DENet, TurNup, UniKP (see GET /api/v1/methods/). CatRange predicts a class of kcat values; readOpenKineticsPredictorOutput uses its geometric midpoint.

Obtaining an API key: The OKP API requires a personal Bearer key (looks like 'ak_...'). Keys are free and need no registration: 1. Open https://predictor.openkinetics.org/api-docs in a browser. 2. In the "API key generator" section, click "Generate". 3. Copy the key shown (it is displayed only once). If you lose it, revoke it on the same page and generate a new one. Keys are tied to your IP and carry a daily prediction quota that resets at midnight UTC.

The key is a secret; do NOT put it in the model adapter (which is shared/committed). Provide it in one of three ways, checked in this order: the apiKey argument below; the OKP_API_KEY environment variable (setenv('OKP_API_KEY',...)); or a plain-text file data/okpApiKey.txt in the model's data folder (this name is git-ignored by GECKO).

Parameters

model : struct

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

Name-Value Arguments

ecRxns : logical

logical vector indicating which reactions to include (default: all reactions).

overwrite : logical

rebuild data/OKP.csv even if it exists (default false; an existing file is reused).

apiKey : char

OKP API key (default: resolved from OKP_API_KEY or data/okpApiKey.txt, see above).

method : char

predictor to use (default: params.okp.method, or 'CataPro').

modelAdapter : ModelAdapter

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

Returns

jobId : char

the OKP job identifier (also written to data/OKP_job.txt).

Examples

jobId = submitOpenKineticsPredictor(model);
jobId = submitOpenKineticsPredictor(model, 'overwrite', true, 'apiKey', 'ak_...', 'method', 'DLKcat');

See also

fetchOpenKineticsPredictor, writeOpenKineticsPredictorInput

updateKcatSources#

function report = updateKcatSources(model, varargin)

Gather the kcat sources that the configuration needs.

Lists the kcat source files that [kcat_assignment] in model_adapter.toml uses (see collectKcats), and gathers those that are missing or outdated with kcatsFromBrenda, kcatsFromECTree, kcatsFromDLKcat and kcatsFromOKP:

  • a file is outdated when its header records other settings than [kcat_sources.] asks for (presets set these for brenda and ec_tree), or, for brenda and ec_tree, another BRENDA release than the BRENDA files in use;

  • brenda and ec_tree are made again; dlkcat reads data/DLKcat.tsv if it exists and runs DLKcat (Docker) otherwise; okp_ submits or fetches a job, and reports it as pending while the job runs;

  • custom.tsv and other files it cannot gather are left as they are.

Requirements are checked first: Docker for a DLKcat run and an OpenKineticsPredictor API key for OKP. Calling it again is safe: files that are current are not gathered again.

Per-source settings are read from model_adapter.toml, for instance:

[kcat_sources.brenda]
aggregation = "median"

[kcat_sources.okp_catapro]
method = "CataPro"

Parameters

model : struct

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

Name-Value Arguments

dryRun : logical

only report what would be gathered (default false).

modelAdapter : ModelAdapter

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

Returns

report : table

one row per source: source, status (current, gathered, pending, outdated, missing, failed or skipped) and note.

Examples

updateKcatSources(ecModel, 'dryRun', true)
updateKcatSources(ecModel);

See also

collectKcats, assignKcats, kcatsFromBrenda, kcatsFromDLKcat, kcatsFromOKP

writeDLKcatInput#

function writtenTable = writeDLKcatInput(model, varargin)

Prepare and write the input file for DLKcat.

Prepares the input for DLKcat, and writes it to data/DLKcat.tsv in the obj.params.path specified in the ModelAdapter.

Parameters

model : struct

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

Name-Value Arguments

ecRxns : logical

for which reactions (from model.ec.rxns) DLKcat should predict kcat values, provided as logical vector with same length as model.ec.rxns (default: all reactions).

modelAdapter : ModelAdapter

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

onlyWithSmiles : logical

whether to only include metabolites with SMILES (default true).

filename : char

path to the input file, including the filename and .tsv extension (default: data/DLKcat.tsv from the obj.params.path folder specified in the modelAdapter).

overwrite : logical

whether existing file should be overwritten (default false, to prevent overwriting a file that already contains DLKcat-predicted kcat values).

Returns

writtenTable : cell

the table written, mainly to be used for testing purposes.

Examples

% optional arguments may be given positionally or as name-value pairs:
writtenTable = writeDLKcatInput(model);
writtenTable = writeDLKcatInput(model, 'onlyWithSmiles', false);

See also

runDLKcat, readDLKcatOutput, extractEnzymeSubstratePairs

writeOpenKineticsPredictorInput#

function writeOpenKineticsPredictorInput(model, varargin)

Write input file for OpenKineticsPredictor.

Prepares input for OpenKineticsPredictor: protein sequences and single- substrate SMILES, which allows the use of the following predictors: DLKcat; EITLEM; UniKP; KinForm-H; KinForm-L; CataPro; CatPred.

The function writes OKP.csv, that can be used as input file at https://predictor.openkinetics.org/

The OpenKineticsPredictor output file can be used to generate a kcatList through readOpenKineticsPredictorOutput.

Parameters

model : struct

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

Name-Value Arguments

ecRxns : logical

logical vector indicating which reactions to include (default: all reactions).

modelAdapter : ModelAdapter

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

onlyWithSmiles : logical

only include entries with SMILES (default true).

overwrite : logical

overwrite existing file (default false).

Examples

% optional arguments may be given positionally or as name-value pairs:
writeOpenKineticsPredictorInput(model, ecRxns);
writeOpenKineticsPredictorInput(model, 'onlyWithSmiles', false);

See also

readOpenKineticsPredictorOutput, writeDLKcatInput