chemistry-db-knowledgebase
Chemistry and biochemistry database router: KEGG REST, PubChem, UniProt, NCBI E-utilities, KEGG C, K, R, EC and map IDs. Use to resolve a protein, metabolite or biochemical question, convert IDs acros
SKILL.mdskills/chemistry-db-knowledgebase/SKILL.md
GitHubChemistry Database Knowledgebase
This skill routes a protein, metabolite or biochemical question to the one reference file that holds the details, and pins the rules every route shares. Read the table, open one reference, and stay out of the others until the question needs them.
Prerequisites
- Python 3 with the standard library only.
scripts/kegg_rest.pyhas no dependencies. - User notification. For each database the first time it is used in a workspace: if
.licenses/<database>_LICENSE.txtdoes not exist in the workspace root, (1) tell the user to check the terms listed in references/terms-and-limits.md, then (2) create the file recording the notification text and a timestamp.<database>iskegg,pubchem,uniprotorncbi. NCBI_API_KEY(optional). It raises NCBI from 3 to 10 requests per second. Read it from the environment; never print it or write it into a file.
Core Rules
- Rate limits are hard limits. KEGG allows 3 calls per second and blocks the address that
exceeds it. Send every KEGG call through
scripts/kegg_rest.py, which holds 2.5 calls per second across all processes. Other limits are in the table under Rate limits. - Answer from tool output. Every identifier, formula, mass, pathway and annotation in a reply comes from an API response in this conversation. When a call returns nothing or an error, report that.
- Convert with the database that owns the target. The route for each ID pair is in references/id-conversion.md. A name or a mass is a query that returns candidates; an accession is an identity.
- Report ambiguity. A conversion is one-to-one, one-to-many or empty. Keep every candidate and the count; picking the first row of a many-to-one is a claim that needs evidence.
- Mouse project defaults. KEGG organism
mmu, NCBI taxon10090. KEGGmmugene IDs are NCBI Gene IDs, sommu:11651is Gene ID 11651. - Notification. When this skill is used, say which databases answered.
Routing
| The question | Open |
|---|---|
| Which pathway, reaction, enzyme, module or K number holds this gene or compound; KEGG syntax | kegg-rest.md |
| What is this chemical: structure, formula, mass, synonyms, bioassays, similarity | pubchem-pug.md |
| What is this protein: function, sequence, reviewed entry, ortholog, ID mapping job | uniprot.md |
| Gene records, RefSeq sequences, PubMed links, taxonomy | ncbi-entrez.md |
| Convert one identifier type to another | id-conversion.md |
| Annotate metabolomics features or spatial metabolomics ion images with compounds | metabolomics-mapping.md |
| Read RNA-seq as metabolic reaction or metabolite predictions | rna-metabolite-prediction.md |
| Terms of use, citations, rate limits per service | terms-and-limits.md |
Decision tree
What do you hold?
|
|- a gene symbol or Ensembl gene ID
| |- want the protein ........ uniprot.md (search gene_exact + organism_id)
| |- want pathways or K ...... id-conversion.md: gene -> NCBI Gene ID -> kegg-rest.md link
|- a UniProt accession ............ id-conversion.md (KEGG conv uniprot, or UniProt map to KEGG)
|- a compound name ................ pubchem-pug.md resolve (candidates) -> id-conversion.md
|- a KEGG C number ................ kegg-rest.md get -> id-conversion.md for CID, ChEBI, InChIKey
|- a K number ..................... kegg-rest.md link ko -> genes, reactions, pathways
|- an m/z or an ion image ......... metabolomics-mapping.md
|- a DE table of enzyme genes ..... rna-metabolite-prediction.md
|- a sequence to fetch ............ ncbi-entrez.md (RefSeq) or uniprot.md (UniProtKB, UniParc)
|- sequence similarity or MSA ..... outside this skill; use a BLAST or alignment tool
Identifier cheat sheet
| Pattern | Namespace | Home database |
|---|---|---|
C00031 |
KEGG compound | KEGG |
D00009 |
KEGG drug | KEGG |
G00001 |
KEGG glycan | KEGG |
R00299 |
KEGG reaction (rn:) |
KEGG |
K00844 |
KEGG Orthology (ko:) |
KEGG |
1.1.1.1 |
Enzyme Commission (ec:) |
KEGG, UniProt |
map00010, mmu00010 |
reference pathway, mouse pathway | KEGG |
M00001 |
KEGG module | KEGG |
mmu:11651 |
KEGG mouse gene = NCBI Gene ID | KEGG |
11651 |
NCBI Gene ID | NCBI |
NM_, NP_, XP_ |
RefSeq transcript, protein | NCBI |
P31750, Q8CF... |
UniProtKB accession | UniProt |
UPI... |
UniParc sequence | UniProt |
ENSMUSG, ENSMUST, ENSMUSP |
Ensembl gene, transcript, protein | Ensembl |
5793 |
PubChem CID (compound) | PubChem |
3333 |
PubChem SID (substance deposit) | PubChem |
WQZGKKKJIJFFOK-GASJEMHNSA-N |
InChIKey: 14-character connectivity block, stereo block, protonation flag | any |
CHEBI:17234 |
ChEBI | EBI |
HMDB0000122 |
HMDB | HMDB |
Rate limits
| Service | Limit | Route |
|---|---|---|
| KEGG REST | 3 calls per second; 403 means blocked | scripts/kegg_rest.py |
| PubChem PUG | 5 requests per second, 400 per minute | one call per 0.25 s |
| NCBI E-utilities | 3 per second, 10 with NCBI_API_KEY |
one call per 0.34 s |
| UniProt REST | no published ceiling; ID mapping runs as asynchronous jobs | poll every 2 s |
Sleep between calls in any loop that touches PubChem or NCBI, and batch inputs wherever the service takes a list.
Shared workflows
Metabolite to everything
Copy this checklist and track progress:
- Step 1: Resolve the name to candidates (
pubchem-pug.md) or take the C number as given. - Step 2: Fetch the KEGG entry for formula, exact mass, reactions, pathways,
DBLINKS. - Step 3: Convert C number to PubChem SID, then to CID, then to InChIKey (
id-conversion.md). - Step 4: Convert to ChEBI with KEGG
conv chebi; keep every ChEBI row. - Step 5: Record the count of candidates at each hop next to the final identifier.
Gene to metabolic role
Copy this checklist and track progress:
- Step 1: Strip the Ensembl version suffix and map to an NCBI Gene ID (
id-conversion.md). - Step 2:
link ko mmu:<GeneID>for K numbers; an empty answer means no KEGG orthology. - Step 3:
link reaction ko:<K>andlink pathway mmu:<GeneID>. - Step 4:
link compound rn:<R>for substrates and products; mark currency metabolites. - Step 5: Pass the gene table to
rna-metabolite-prediction.mdfor the interpretation limits.
Common mistakes
- Treating
conv pubchemoutput as CIDs. KEGG returns PubChem SIDs.C00031givespubchem:3333, and CID 5793 is one hop further through PUGsubstance/sid/<SID>/cids. - Taking the first name hit. PubChem and KEGG name searches return several candidates; stereoisomers and salts share names.
- Matching on mass alone.
C00031glucose,C00095fructose andC00124galactose share exact mass 180.063388. Mass defines a candidate set. - Using a reference pathway for organism genes.
map00010lists no mouse genes; usemmu00010. - Passing more than 10 entries in one KEGG
get. The wrapper batches; raw calls fail. - Forgetting the Ensembl version suffix. UniProt returns
ENSMUSG00000001729.12infailedIds;ENSMUSG00000001729(Akt1) maps. Direct Ensembl toGeneIDis an invalid pair. - Reading KEGG compound entries as defined structures. Some are generic (R groups,
polymers); some drugs (
D) duplicate a compound (C) underSame as. - Using KEGG output beyond academic terms. The REST API is licensed for academic use.
Reference materials
- kegg-rest.md, pubchem-pug.md, uniprot.md, ncbi-entrez.md
- id-conversion.md, metabolomics-mapping.md, rna-metabolite-prediction.md, terms-and-limits.md
scripts/kegg_rest.py— throttled KEGG client; runpython3 -I scripts/kegg_rest.py -hNOTICEandLICENSE— Apache-2.0 terms and the attribution for the derived material
See also
gatom-metabolomic-predictions— Downstream consumer; solves the active metabolic module from the DE table and the KEGG-derived networkbulkirna— Prerequisite; produces the DE table whose gene IDs enter the gene routebulk-rnaseq-gsea— Sibling; tests KEGG pathway sets by enrichment, where this skill resolves their membersannotate-bulk-rnaseq-data— Prerequisite; attaches the gene symbols and IDs this skill converts