Enzyme & EC data (Python)#

geckopy objects in geckopy.get_enzyme_data.

Functions#

Function

Summary

copy_ec_to_gem

Copy EC codes from model.ec.eccodes to per-reaction

fill_eccodes_from_database

Populate model.ec.eccodes by looking each reaction's genes

fill_eccodes_from_gem

Populate model.ec.eccodes from per-reaction ec-code annotations.

find_ec_in_db

Collect EC codes for a reaction's genes from a protein database.

Reference#

copy_ec_to_gem#

copy_ec_to_gem(model: 'EcModel', *, overwrite: bool=False)

Copy EC codes from model.ec.eccodes to per-reaction

annotation['ec-code'] (the cobrapy-side mirror of MATLAB's top-level model.eccodes).

Ported from GECKO MATLAB: src/geckomat/get_enzyme_data/copyECtoGEM.m.

For each entry of model.ec.rxns (after stripping a 4-char prefix when the model is in gecko-light mode), the corresponding cobra.Reaction's annotation['ec-code'] is written as a list of EC tokens split from the ;-joined ec.eccodes[i] string. Empty ec.eccodes entries are skipped: they neither create new annotations nor clobber existing ones, even with overwrite=True.

With overwrite=False (default) only reactions whose current ec-code annotation is missing or empty ("", [], None) are updated. With overwrite=True any non-empty ec.eccodes[i] replaces the current annotation.

Reactions in the cobra model that are absent from model.ec.rxns are left untouched. Entries of model.ec.rxns that do not match any cobra reaction are silently skipped.

Parameters

model

EcModel with populated model.ec.rxns and model.ec.eccodes (typically by some combination of fill_eccodes_from_gem, fill_eccodes_from_database, etc.). Mutated in place.

overwrite

See above.

fill_eccodes_from_database#

fill_eccodes_from_database(model: 'EcModel', uniprot_db: 'UniprotDB', *, kegg_db: Optional['KeggDB']=None, ec_rxns: Optional[Iterable[str]]=None, action: Literal['display', 'ignore']='display')

Populate model.ec.eccodes by looking each reaction's genes

up in a UniProt database.

Ported from GECKO MATLAB: src/geckomat/get_enzyme_data/getECfromDatabase.m.

For each entry of model.ec.rxns selected by ec_rxns:

  • Gather the gene IDs catalysing the reaction from model.ec.rxn_enz_mat row i.

  • Pass them to find_ec_in_db along with a pre-built gene -> protein-indices map.

  • Store the resulting ;-joined EC string in model.ec.eccodes[i].

The adapter used for gene-ID translation is read from model.adapter.

The gene -> protein-indices map is built once before the loop. It tries the adapter's uniprotConversion.tsv table first: if that table changes any gene IDs, each model gene maps to one UniProt ID which uniquely identifies one protein. Otherwise it falls back to name-based lookup via adapter.get_uniprot_compatible_genes, and a single gene may map to several proteins (which is how conflicts arise).

If kegg_db is supplied, the KEGG fallback fires for any reaction whose UniProt-derived EC is empty or ends with - (a wildcard). The KEGG hit replaces the UniProt result when non-empty.

Parameters

model

EcModel with model.ec.rxns, model.ec.genes, and model.ec.rxn_enz_mat already populated (typically by allocate_ec_for_catalyzed_reactions, populate_enzyme_data, and build_rxn_enzyme_coupling respectively). Mutated in place.

uniprot_db

Pre-loaded UniProt database. Accessed for its eccodes, mw, genes, and ids fields.

ec_rxns

Optional iterable of reaction IDs (each must appear in model.ec.rxns) selecting which entries of model.ec.eccodes to update. None means update all. Unknown IDs raise ValueError.

action

Behaviour when a gene maps to proteins with multiple distinct EC strings. 'display' (default) emits an aggregated warning at the end of the run listing every conflicting (rxn, gene, proteins) triple. 'ignore' suppresses the aggregated warning. Per-gene warnings from find_ec_in_db are emitted in both modes.

Raises

ValueError

If model.adapter is None; if action is not 'display' or 'ignore'; or if any ID in ec_rxns is not present in model.ec.rxns.

fill_eccodes_from_gem#

fill_eccodes_from_gem(model: 'EcModel', ec_rxns: Optional[Iterable[str]]=None)

Populate model.ec.eccodes from per-reaction ec-code annotations.

Ported from GECKO MATLAB: src/geckomat/get_enzyme_data/getECfromGEM.m.

For each entry of model.ec.rxns, looks up the corresponding cobra.Reaction (stripping a 4-char prefix first when the model is in gecko-light mode), reads reaction.annotation['ec-code'], validates the resulting string against the canonical <ec>(;<ec>)* pattern (with <ec> being four dot-separated levels of either a non-negative integer or -), and stores the result in model.ec.eccodes[i]. Strings that fail validation are replaced with "" and listed in a single logger.warning.

Parameters

model

EcModel with model.ec.rxns already allocated (typically by allocate_ec_for_catalyzed_reactions). Mutated in place.

ec_rxns

Optional iterable of reaction IDs (each must appear in model.ec.rxns) selecting which entries of ec.eccodes to update. If None (default), every entry is rewritten. Unknown IDs raise ValueError.

find_ec_in_db#

find_ec_in_db(gene_set: list[str], db_eccodes: list[str], db_mw: np.ndarray, gene_to_protein_indices: dict[str, list[int]], *, conflicts: list[tuple[str, list[int]]] | None=None)

Collect EC codes for a reaction's genes from a protein database.

Ported from GECKO MATLAB: src/geckomat/get_enzyme_data/findECInDB.m.

Per-gene resolution:

  • Look up the gene's protein indices in gene_to_protein_indices. Missing keys count as no DB match.

  • Filter to proteins with non-empty db_eccodes.

  • If those proteins agree on a single EC string (or there is only one protein), pick the lightest-MW one's string. NaN MWs are treated as +inf so a NaN-only group falls back to the first.

  • If they disagree, pick the first distinct string in DB order (matching MATLAB unique('stable')) and emit a logger.warning listing the gene as a conflict.

Cross-gene reconciliation (for complexes with multiple subunits):

  • UNION of all gene-level token sets, with wildcard subsumption (1.1.1.1 removes 1.1.1.-).

  • INTERSECTION over the same, pairwise.

  • Use intersection if non-empty, else union. Final result is wildcard-deduped and joined with ;.

Parameters

gene_set

Gene IDs from one reaction's GPR (one AND-clause after isozyme expansion). Order matters for reproducibility of the cross-gene UNION / INTERSECTION ordering.

db_eccodes

EC string per protein row in the database. Empty string means "no EC for this protein". Multi-EC strings (;-joined) are permitted.

db_mw

Molecular weight per protein row, in Da. NaN is tolerated.

gene_to_protein_indices

Maps gene ID to a list of protein row indices in the DB. Built once by getECfromDatabase before iterating reactions. Missing keys mean "this gene has no DB match" (silent).

conflicts

Optional accumulator. If provided, (gene, protein_indices) tuples are appended for every gene in gene_set that maps to multiple distinct EC strings, where protein_indices are the DB row indices of the first protein per distinct EC (mirroring MATLAB's unique('stable') indexing). Useful for aggregating conflicts across many calls without scraping logs.

Returns

str

;-joined EC tokens (no EC prefix), e.g. "1.1.1.1;2.7.7.7". Empty string if no gene contributed any EC.