Kegg database querying

KEGG Database Querying

Summary

Query the KEGG database to retrieve metabolic pathway and reaction data for specified organisms, enabling automated reconstruction of metabolic networks. This skill is essential when you need to programmatically obtain organism-specific metabolic information to build comparative network models.

When to use

Apply this skill when you have identified two or more organisms (via their KEGG organism codes, e.g., 'hsa' for Homo sapiens) and need to retrieve their complete metabolic pathway and reaction datasets as a prerequisite for network reconstruction or comparative metabolic analysis. Use it specifically when organism identifiers are available and the downstream goal is to build structural or functional representations of metabolic networks.

When NOT to use

• When metabolic network data has already been retrieved and stored locally; querying again would be redundant and inefficient.
• When working with custom or non-KEGG metabolic databases; this skill is KEGG-specific and cannot be applied to other pathway databases without adaptation.
• When only a small subset of hand-curated reactions is needed; full KEGG queries retrieve comprehensive data that may exceed the scope of focused studies.

Inputs

• organism identifiers (KEGG codes, e.g., 'hsa', 'ptr')
• KEGG database connection or API endpoint
• configuration file specifying organisms and pathways (e.g., organismList.txt, pathwayList.txt)

Outputs

• metabolic pathway data per organism (pathway IDs, definitions, associated reactions)
• metabolic reaction data per organism (reaction equations, enzyme IDs, stoichiometric coefficients)
• organism-specific metabolic data records ready for network reconstruction

How to apply

Load organism identifiers (KEGG codes) from a configuration file such as organismList.txt. Query the KEGG database programmatically to retrieve metabolic pathway and reaction data for each selected organism. The retrieved data should include pathway definitions, reaction stoichiometry, and enzyme associations. Validate that all expected pathways and reactions for each organism have been successfully retrieved before proceeding to network reconstruction. The query results form the raw input layer that will be passed to network topology builders (e.g., MetNet) to generate structural and functional network representations. Ensure that the KEGG version and query parameters are consistent across all organisms being compared to maintain comparability.

Related tools

• MetNet (Java tool that consumes KEGG metabolic data queried by this skill to automatically reconstruct metabolic network topology and functional representations) — https://github.com/simeoni-biolab/MetNet
• KEGG (Source database from which metabolic pathway and reaction data are retrieved via programmatic queries)

Examples

java -jar MetNet.jar hsa ptr set

Evaluation signals

• Verify that the number of retrieved pathways and reactions per organism matches expected counts from KEGG documentation or a manual spot check.
• Confirm that all organism identifiers in the input list were successfully queried and no organisms were skipped or failed silently.
• Validate that reaction data includes required fields: reaction equations, enzyme EC numbers, and stoichiometric coefficients.
• Check that retrieved data for two organisms can be independently passed to MetNet for network reconstruction without schema errors.
• Ensure query timestamps and KEGG version metadata are recorded to enable reproducibility and version tracking across comparative analyses.

Limitations

• KEGG data quality and completeness varies by organism; less-studied organisms may have incomplete pathway annotations.
• KEGG is a commercial and subscription-based resource for some use cases; access restrictions or rate limits may apply depending on usage context.
• The retrieved data reflects KEGG's current curation state; pathway and reaction annotations are periodically updated, so reproducibility of results from different KEGG versions may differ.
• Organism selection is constrained to organisms present in KEGG; custom or newly sequenced organisms not yet in the database cannot be queried directly.

Evidence

• [other] Query KEGG database to retrieve metabolic pathway and reaction data for each of the two organisms.: "Query KEGG database to retrieve metabolic pathway and reaction data for each of the two organisms"
• [readme] Load organism identifiers from organismList.txt and pathwayList.txt configuration files.: "organismList.txt : configuration file containing the list of organisms available in KEGG"
• [other] MetNet automatically reconstructs metabolic networks by retrieving metabolic data from KEGG for two organisms selected by the user.: "MetNet automatically reconstructs metabolic networks by retrieving metabolic data from KEGG for two organisms selected by the user"
• [readme] MetNet is a Java tool that makes it possible to automatically reconstruct the metabolic network of two organisms selected in KEGG.: "MetNet is a Java tool that makes it possible to automatically reconstruct the metabolic network of two organisms selected in KEGG"
• [readme] Please ensure that the configuration files organismList.txt and pathwayList.txt are in the tool's directory.: "Please ensure that the configuration files organismList.txt and pathwayList.txt are in the tool's directory"