Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion databases/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

GECKO does not include BRENDA data. `fetchBrendaAsset` downloads the files of the [toolbox-assets](https://github.com/CompMetEng/toolbox-assets) release `brenda-2026.1-1` ([BRENDA](https://www.brenda-enzymes.org) 2026.1, CC BY 4.0) on first use into `databases/brenda-2026.1-1`, checked against the manifest checksums. geckopy uses the same release. A project can use its own BRENDA files instead, in `data/brenda`, written by the `geckopy brenda-refresh` CLI of [geckopy](https://github.com/CompMetEng/geckopy).

- `kcat.tsv`: kcat values per organism, reaction and substrate. Both a per-triple maximum (`kcat_max`) and median (`kcat_median`) are recorded. Which one is used is set by `params.kcatAggregation` on the model adapter, or per call with `fuzzyKcatMatching(model,'kcatAggregation','median')`; the default is `max`.
- `kcat.tsv`: kcat values per organism, reaction and substrate. Both a per-triple maximum (`kcat_max`) and median (`kcat_median`) are recorded. Which one is used is set by `aggregation` in `[kcat_sources.brenda]` of `model_adapter.toml` (the preset's: `median` for the default preset, `max` for `gecko_classic`), or per call with `fuzzyKcatMatching(model,'kcatAggregation','median')`.
- `sa.tsv`: specific activities per organism, reaction and substrate, with a maximum (`sa_max`) and median (`sa_median`); `loadBRENDAdata` uses `sa_max`.
- `mw.tsv`: molecular weights per organism and reaction (without explicitly referring to a protein identifier).
- `measurements.tsv`: one row per wild-type k<sub>cat</sub> measurement with an EC number: EC number, substrate (name and InChIKey), organism, UniProt accession and sequence id, k<sub>cat</sub> (1/s; the geometric midpoint of a range), temperature, pH and PubMed id. Values more than four orders of magnitude below their EC class, and clusters of values below 0.01 /s that sit three orders of magnitude under the other values of their EC number, are left out as unit errors. `kcatsFromECTree` reads it (see `loadBrendaMeasurements`).
Expand Down
32 changes: 0 additions & 32 deletions src/deprecated/adapterTemplate.m
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,6 @@
% Provide your organism scientific name
obj.params.org_name = 'genus species';

% Which BRENDA aggregate fuzzyKcatMatching reads for each
% (EC, substrate, organism) triple: 'max' (the highest
% turnover reported) or 'median' (the middle one). Can also
% be given per call as
% fuzzyKcatMatching(model,'kcatAggregation','median').
obj.params.kcatAggregation = 'max';

% Taxonomic identifier for Complex Portal
obj.params.complex.taxonomicID = [];

Expand Down Expand Up @@ -96,31 +89,6 @@
% this does not interfere with them catalyzing reactions in
% different compartments). Typically, cytoplasm is chosen.
obj.params.enzyme_comp = 'cytoplasm';

%% Hyperparameters for evotune (CMA-ES) kcat fitting
% Default initial uncertainty (standard deviation in log-space) for kcat values
obj.params.evotune.sigma0logDefault = 0.5;
% Data sources for kcat values, ordered from least to most trusted
obj.params.evotune.kcatSources = {'dlkcat','brenda','custom'};
% Initial uncertainty for each source (lower = more trusted data)
obj.params.evotune.sigma0logSource = [0.4; 0.2; 0.1];

% Weight on the max-growth RMSE against the flux RMSE:
% (rmseFlux + w*rmseMaxGrowth) / (w+1). At 1 both count equally.
obj.params.evotune.maxGrowthWeight = 1.0;
% Weight on a prior term in the search objective,
% rmse + w*mean((log(k/k0)/sigma0log)^2). Keeps large corrections
% reproducible across seeds; 0 scores on RMSE alone.
obj.params.evotune.priorPenaltyWeight = 0.03;
% Give isozyme copies of one reaction (sharing a prior value and
% a source) a single shared kcat, so the search cannot invent a
% distinction the kcat assignment never made.
obj.params.evotune.tieIsozymes = true;

% Stop optimization when RMSE falls below this threshold
obj.params.evotune.rmseThreshold = 0.2;
% Maximum number of CMA-ES generations before termination
obj.params.evotune.maxGenerations = 150;
end

% function ecModel = makeModelAnaerobic(ecModel)
Expand Down
6 changes: 3 additions & 3 deletions src/download_databases/loadBRENDAdata.m
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
% a loaded model adapter (default: the current default model adapter).
% kcatAggregation : char
% which aggregate to read from kcat.tsv and sa.tsv, 'max' or
% 'median' (default: params.kcatAggregation from the model adapter,
% or 'max' if the adapter does not set it). A triple's max is the
% 'median' (default: [kcat_sources.brenda] aggregation as resolved from the preset or the
% stages (median for the default preset, max when no stage sets it)). A triple's max is the
% highest turnover reported for it; its median is the middle one.
% filterOutlierKcats : logical
% whether to drop a row whose kcat is implausibly low for its EC
Expand Down Expand Up @@ -58,7 +58,7 @@
'kcatAggregation', [], @(x) assert(isempty(x) || any(strcmpi(x, ...
{'max','median'})), ...
'loadBRENDAdata:invalidKcatAggregation', ...
'kcatAggregation must be ''max'' or ''median''.'); ...
'aggregation must be max or median'); ...
'filterOutlierKcats', true, @(x) assert((islogical(x) || isnumeric(x)) && ...
isscalar(x), ...
'loadBRENDAdata:invalidFilterOutlierKcats', ...
Expand Down
19 changes: 10 additions & 9 deletions src/download_databases/resolveKcatAggregation.m
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,11 @@
%
% The BRENDA snapshot records both a maximum and a median per
% (EC, substrate, organism) triple. Which one a run uses can be given per
% call, or once on the model adapter as params.kcatAggregation; an
% adapter that sets neither gets 'max', which is what GECKO has always
% used.
% call. Without one, it is [kcat_sources.brenda] aggregation of the kcat
% assignment configuration (kcatAssignmentConfig): the preset's, which is
% 'median' for the default preset brenda_ec_tree and 'max' for
% gecko_classic, or the one that model_adapter.toml sets. A configuration
% in which no stage sets an aggregation for brenda gives 'max'.
%
% Input Arguments
% ---------------
Expand All @@ -25,18 +27,17 @@
% loadBRENDAdata, fuzzyKcatMatching

if isempty(kcatAggregation)
params = modelAdapter.getParameters();
if isfield(params,'kcatAggregation') && ~isempty(params.kcatAggregation)
kcatAggregation = params.kcatAggregation;
else
kcatAggregation = 'max';
config = kcatAssignmentConfig(modelAdapter.getParameters());
kcatAggregation = 'max';
if isfield(config.sources, 'brenda') && isfield(config.sources.brenda, 'aggregation')
kcatAggregation = config.sources.brenda.aggregation;
end
end

if ~(ischar(kcatAggregation) || isstring(kcatAggregation)) || ...
~any(strcmpi(kcatAggregation,{'max','median'}))
error('resolveKcatAggregation:invalidKcatAggregation', ...
'kcatAggregation must be ''max'' or ''median''.')
'aggregation must be max or median')
end
kcatAggregation = lower(char(kcatAggregation));
end
6 changes: 5 additions & 1 deletion src/gather_kcats/fuzzyKcatMatching.m
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@
% forceWClvl : double
% number of extra levels, from the right, replaced by a wildcard (on top
% of any wildcard already in the code; default 0).
% kcatAggregation : char
% which BRENDA aggregate to read, 'max' or 'median' (default:
% [kcat_sources.brenda] aggregation as resolved from the preset or the
% stages (median for the default preset, max when no stage sets it)).
%
% Returns
% -------
Expand Down Expand Up @@ -102,7 +106,7 @@
'kcatAggregation', [], @(x) assert(isempty(x) || any(strcmpi(x, ...
{'max','median'})), ...
'fuzzyKcatMatching:invalidKcatAggregation', ...
'kcatAggregation must be ''max'' or ''median''.')});
'aggregation must be max or median')});
ecRxns = p.ecRxns;
modelAdapter = p.modelAdapter;
forceWClvl = p.forceWClvl;
Expand Down
12 changes: 8 additions & 4 deletions src/gather_kcats/kcatAssignmentConfig.m
Original file line number Diff line number Diff line change
Expand Up @@ -81,19 +81,23 @@
end
end
% The okp group: the OKP methods of [kcat_sources.okp] methods.
known = {'CataPro','CatPred','CatRange','DLKcat','EITLEM','KinForm-H','KinForm-L', ...
'OmniESI','OmniESI-O2DENet','TurNup','UniKP'};
% The default: KinForm-H, as the default of params.okp.method.
% The methods kcatsFromOKP accepts: those that predict from one enzyme and
% one substrate (CatPred and TurNup read whole reactions).
known = {'CataPro','CatRange','DLKcat','EITLEM','KinForm-H','KinForm-L', ...
'OmniESI','OmniESI-O2DENet','UniKP'};
% The default: KinForm-H.
config.okpMethods = {'KinForm-H'};
if isfield(config.sources, 'okp') && isfield(config.sources.okp, 'methods') && ~isempty(config.sources.okp.methods)
config.okpMethods = cellstr(config.sources.okp.methods);
config.okpMethods = config.okpMethods(:)';
end
unknown = setdiff(config.okpMethods, known);
unknown = unique(config.okpMethods(~ismember(config.okpMethods, known)), 'stable');
if ~isempty(unknown)
error('kcatAssignment:config', 'Unknown OKP methods in [kcat_sources.okp] methods: %s; methods: %s.', ...
strjoin(unknown, ', '), strjoin(known, ', '))
end
% The file of a method: okp_ and the lower-case method name, with runs of
% characters other than letters and digits replaced by _.
okpFiles = cellfun(@(m) ['okp_' lower(regexprep(regexprep(m, '[^A-Za-z0-9]+', '_'), '^_+|_+$', ''))], ...
config.okpMethods, 'UniformOutput', false);
for s = 1:numel(config.stages)
Expand Down
4 changes: 2 additions & 2 deletions src/gather_kcats/kcatsFromBrenda.m
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@
% --------------------
% 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').
% 'max' or 'median' (default: [kcat_sources.brenda] aggregation as resolved from the preset or the
% stages (median for the default preset, max when no stage sets it)).
% forceWClvl : double
% number of extra levels, from the right, replaced by a wildcard in the
% EC numbers (on top of any wildcard already in the code; default 0).
Expand Down
22 changes: 11 additions & 11 deletions src/gather_kcats/kcatsFromOKP.m
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,11 @@
% 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 'KinForm-H').
% OKP method that predicts from one enzyme and one substrate: 'CataPro',
% 'CatRange', 'DLKcat', 'EITLEM', 'KinForm-H', 'KinForm-L', 'OmniESI',
% 'OmniESI-O2DENet' or 'UniKP' (default: the first entry of
% [kcat_sources.okp] methods of the model adapter, KinForm-H when it
% lists none).
% wait : logical
% wait until the job is done (default false).
% resubmit : logical
Expand Down Expand Up @@ -97,17 +99,16 @@
params = modelAdapter.params;
method = char(p.method);
if isempty(method)
if isfield(params, 'okp') && isfield(params.okp, 'method') && ~isempty(params.okp.method)
method = char(params.okp.method);
else
method = 'KinForm-H';
end
config = kcatAssignmentConfig(params);
method = config.okpMethods{1};
end
if any(strcmp(method, {'CatPred', 'TurNup'}))
error('kcatsFromOKP:method', ['%s reads whole reactions (its substrate set, and products ' ...
'for TurNup); kcatsFromOKP submits enzyme-substrate pairs only.'], method)
end
tag = lower(regexprep(method, '[^A-Za-z0-9]+', '_'));
% The file name of a method: lower case, runs of characters other than
% letters and digits replaced by _ (the same rule as okp_<method> sources).
tag = lower(regexprep(regexprep(method, '[^A-Za-z0-9]+', '_'), '^_+|_+$', ''));
dataDir = fullfile(params.path, 'data');
jobFile = fullfile(dataDir, ['OKP_job_' tag '.txt']);
outFile = fullfile(dataDir, ['OKP_output_' tag '.csv']);
Expand Down Expand Up @@ -272,8 +273,7 @@ function checkOptions(args, names, functionName)
error('ecRxns should be a logical vector with length equal to model.ec.rxns')
end
% Request options: defaults, then params.okp, then the method of this job.
okp = struct('method','KinForm-H', ...
'handleLongSequences','truncate', ...
okp = struct('handleLongSequences','truncate', ...
'includeSimilarityColumns',true,'canonicalizeSubstrates',true);
if isfield(params,'okp')
fn = fieldnames(params.okp);
Expand Down
33 changes: 18 additions & 15 deletions src/gather_kcats/updateKcatSources.m
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,13 @@
% [kcat_sources.brenda]
% aggregation = "median"
%
% [kcat_sources.okp_catapro]
% method = "CataPro"
% [kcat_sources.okp]
% methods = ["CataPro", "KinForm-H"]
%
% The keys that a [kcat_sources.<name>] table can set are aggregation and
% force_wildcard_level for brenda, k for ec_tree, k, min_identity and
% coverage for homologs, and methods for okp; the okp_<method> files
% have none (their method is the one whose file name they carry).
%
% Parameters
% ----------
Expand Down Expand Up @@ -160,7 +165,7 @@
st = 'pending'; nt = 'OKP job for DLKcat still running; call again later';
end
else % okp_<method>
method = okpMethod(name, wanted);
method = okpMethod(name);
resolveOkpApiKey('', modelAdapter.params.path); % errors without a key
[~, done] = kcatsFromOKP(model, 'method', method, 'saveAs', name, 'modelAdapter', modelAdapter);
if ~done
Expand All @@ -172,20 +177,18 @@
end
end

function method = okpMethod(name, wanted)
% The OKP method of okp_<method>: from [kcat_sources.okp_<method>] method,
% or the known method whose name gives this file name.
if isfield(wanted, 'method')
method = char(wanted.method);
return
end
known = {'CataPro','CatPred','CatRange','DLKcat','EITLEM','KinForm-H','KinForm-L', ...
'OmniESI','OmniESI-O2DENet','TurNup','UniKP'};
tags = cellfun(@(m) ['okp_' lower(regexprep(m, '[^A-Za-z0-9]+', '_'))], known, 'UniformOutput', false);
function method = okpMethod(name)
% The OKP method of okp_<method>: the known method whose file name is name,
% that is okp_ and the lower-case method name, with runs of characters
% other than letters and digits replaced by _.
known = {'CataPro','CatRange','DLKcat','EITLEM','KinForm-H','KinForm-L', ...
'OmniESI','OmniESI-O2DENet','UniKP'};
tags = cellfun(@(m) ['okp_' lower(regexprep(regexprep(m, '[^A-Za-z0-9]+', '_'), '^_+|_+$', ''))], ...
known, 'UniformOutput', false);
hit = strcmp(tags, name);
if ~any(hit)
error('updateKcatSources:okpMethod', ['Set the OKP method of %s in model_adapter.toml: ' ...
'[kcat_sources.%s] method = "..."'], name, name)
error('updateKcatSources:okpMethod', ['%s is not the file of a known OKP method; ' ...
'the files are %s.'], name, strjoin(tags, ', '))
end
method = known{hit};
end
Expand Down
3 changes: 2 additions & 1 deletion src/kcat_tuning/evotune/cmaesKcatTuning.m
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
% rate.
%
% Configuration comes entirely from modelAdapter.params.evotune: trust
% tiers (kcatSources/sigma0logSource/sigma0logDefault), maxGrowthWeight,
% tiers (kcatSources/sigma0logSource, from [evotune.source_groups], and
% sigma0logDefault), maxGrowthWeight,
% priorPenaltyWeight and tieIsozymes control the search, and
% maxGenerations/rmseThreshold are its stopping conditions.
%
Expand Down
49 changes: 39 additions & 10 deletions src/kcat_tuning/evotune/resolveTunableContext.m
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,29 @@
% Shared by screenKcatLeverage and cmaesKcatTuning so a screen and the
% tuning run it feeds are always looking at exactly the same parameters.
%
% A kcat belongs to the group whose params.kcatSources entry equals the
% origin of its ec.source or its whole ec.source (case-insensitive, see
% parseKcatSource), so
% A kcat belongs to the group of the first params.kcatSources entry that
% matches its source, and is labelled with the name of that group
% (params.kcatGroups, one per entry). Without groups the error is raised:
% No evotune source groups: set [evotune.source_groups] in model_adapter.toml. An entry matches the origin of the kcat's ec.source
% or its whole ec.source (case-insensitive, see parseKcatSource), so
% 'brenda (wc=0, origin=1)' is in the group of 'brenda',
% 'combined (sd=0.10, n=2)' in the group of 'combined' and
% 'brenda (wc=0, origin=1) | tuned=cmaes (prior=2)' in the group of 'brenda',
% with that group's sigma0logSource. When a source matches the entries of
% several groups, the first matching entry in params.kcatSources gives the
% group.
% with that group's sigma0logSource. An entry that ends in * is a prefix
% pattern on the origin ('okp_*' covers okp_eitlem_kinetics and
% okp_kinform_h). Exact entries are tried first, over all entries in order;
% then the patterns, the longest prefix first, and in the order of
% params.kcatSources among equal prefixes. Kcats that match no entry get
% sigma0logDefault; when more than 20 % of the tunable kcats match none,
% a warning (resolveTunableContext:unlabelled) lists up to five origins,
% the most common first and in alphabetical order among equal counts.
%
% Parameters
% ----------
% ecModel : struct
% ecModel with a populated ec.kcat.
% params : struct
% modelAdapter.params.evotune (kcatSources, sigma0logSource,
% modelAdapter.params.evotune (kcatSources, kcatGroups, sigma0logSource,
% sigma0logDefault, tieIsozymes).
% tunableMask : logical
% same length as ecModel.ec.rxns; [] to consider every kcat > 0.
Expand Down Expand Up @@ -64,12 +71,34 @@
groups = repmat({'unlabelled'}, numel(tunableIdx), 1);
sigma0log = params.sigma0logDefault * ones(numel(tunableIdx),1);
assigned = false(numel(tunableIdx),1);
for i = 1:numel(params.kcatSources)
idx = ~assigned & (strcmpi(sourceNames, params.kcatSources{i}) | strcmpi(sources, params.kcatSources{i}));
entries = params.kcatSources(:)';
if ~isfield(params, 'kcatGroups') || isempty(params.kcatGroups)
error('GECKO:resolveTunableContext', ...
'No evotune source groups: set [evotune.source_groups] in model_adapter.toml')
end
entryGroup = params.kcatGroups(:)';
isPattern = endsWith(entries, '*');
patternLength = cellfun(@numel, entries);
[~, order] = sort(patternLength(isPattern), 'descend'); % stable: ties keep the group order
patternIdx = find(isPattern);
for i = [find(~isPattern), patternIdx(order)]
if isPattern(i)
idx = ~assigned & startsWith(sourceNames, entries{i}(1:end-1), 'IgnoreCase', true);
else
idx = ~assigned & (strcmpi(sourceNames, entries{i}) | strcmpi(sources, entries{i}));
end
assigned(idx) = true;
groups(idx) = params.kcatSources(i);
groups(idx) = entryGroup(i);
sigma0log(idx) = params.sigma0logSource(i);
end
if mean(~assigned) > 0.2
[names, ~, k] = unique(sourceNames(~assigned));
[~, byCount] = sort(accumarray(k, 1), 'descend');
names = names(byCount(1:min(5, end)));
warning('resolveTunableContext:unlabelled', ...
'%d of %d tunable kcats match no evotune source group and get sigma0_log_default (%g); origins: %s', ...
sum(~assigned), numel(assigned), params.sigma0logDefault, strjoin(names, ', '))
end

if isfield(params,'tieIsozymes') && params.tieIsozymes
tieMap = isozymeTieMap(ecRxnIdsTunable, kcat0, 'sources', groups);
Expand Down
5 changes: 4 additions & 1 deletion src/kcat_tuning/sensitivityTuning.m
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
% --------------------
% desiredGrowthRate : double
% kcats will be relaxed until this growth rate is reached (default: the
% experimental growth rate params.gR_exp from the model adapter).
% experimental growth rate gr_exp from the model adapter).
% modelAdapter : ModelAdapter
% a loaded model adapter (default: the current default model adapter).
% foldChange : double
Expand Down Expand Up @@ -82,6 +82,9 @@
end
params = modelAdapter.params;
if isempty(desiredGrowthRate)
if ~isfield(params, 'gR_exp') || isempty(params.gR_exp)
error('GECKO:grExpNotSet', 'gr_exp is not set in model_adapter.toml')
end
desiredGrowthRate = params.gR_exp;
end

Expand Down
Loading
Loading