Case 1: From a UniProt ID to KEGG information

This walkthrough starts with a UniProt identifier and retrieves its KEGG gene, sequences, orthology group, reactions, and pathways.

1. Convert an outside identifier to a KEGG identifier

kegg_conv maps identifiers between KEGG and outside databases. Some common gene / protein identifier prefixes are:

Only identifiers with a hit in KEGG are returned:

conv = KEGGAPI.kegg_conv("genes", "uniprot:A0A072UR65")
@assert conv isa KEGGAPI.KeggTupleList
DataFrame(conv.data, conv.colnames)

Several identifiers from the same database can be converted in one call by passing a vector. KEGGAPI splits inputs longer than 10 entries into request batches:

entries = ["uniprot:A0A072UR65", "uniprot:P12345"]
conv = KEGGAPI.kegg_conv("genes", entries)
@assert conv isa KEGGAPI.KeggTupleList
conv.url

1-element Vector{String}:
 "https://rest.kegg.jp/conv/genes/uniprot:A0A072UR65+uniprot:P12345"

To convert from KEGG to an outside database, reverse the target and source:

conv = KEGGAPI.kegg_conv("ncbi-proteinid", "mtr:25493984")
@assert conv isa KEGGAPI.KeggTupleList
DataFrame(conv.data, conv.colnames)

2. Retrieve the gene entry

Use kegg_get to fetch the full flat-file entry for a KEGG gene. A single entry is returned as a String in the .data field:

gene = KEGGAPI.kegg_get("mtr:25493984")
@assert gene.url isa String && gene.data isa String
println(join(first(split(gene.data, "\n"), 8), "\n"))

ENTRY       25493984          CDS       T01716
NAME        (RefSeq) class V chitinase CHIT5b
ORTHOLOGY   K01183  chitinase [EC:3.2.1.14]
ORGANISM    mtr  Medicago truncatula (barrel medic)
PATHWAY     mtr00520  Amino sugar and nucleotide sugar metabolism
            mtr01100  Metabolic pathways
BRITE       KEGG Orthology (KO) [BR:mtr00001]
             09100 Metabolism

3. Download sequences

kegg_get can return amino-acid (:aaseq) or nucleotide (:ntseq) FASTA sequences. For vector input, .data holds one FASTA record per requested entry:

seqs = KEGGAPI.kegg_get(["mtr:25493984", "shz:shn_30305"], :aaseq)
@assert length(seqs.data) == 2 && all(startswith(">"), seqs.data)
first(split(first(seqs.data), '\n'))

">mtr:25493984 K01183 chitinase [EC:3.2.1.14] | (RefSeq) class V chitinase CHIT5b (A)"

Write the records with write("aaseq.fasta", join(seqs.data, '\n')) or pass them to a FASTA package.

4. Orthology, reactions and pathways

kegg_link finds cross-references between databases. The orthology (KO) group for the gene:

ko = KEGGAPI.kegg_link("ko", "mtr:25493984")
@assert ko isa KEGGAPI.KeggTupleList
DataFrame(ko.data, ko.colnames)

Reactions associated with that ortholog:

rxns = KEGGAPI.kegg_link("reaction", "K01183")
@assert rxns isa KEGGAPI.KeggTupleList
DataFrame(rxns.data, rxns.colnames)

Pathways the gene participates in:

paths = KEGGAPI.kegg_link("pathway", "mtr:25493984")
@assert paths isa KEGGAPI.KeggTupleList
DataFrame(paths.data, paths.colnames)

5. All genes in an orthology group

The same kegg_link call, targeting genes, expands an orthology group into every member gene across organisms:

ko_genes = KEGGAPI.kegg_link("genes", "K01183")
@assert ko_genes isa KEGGAPI.KeggTupleList
first(DataFrame(ko_genes.data, ko_genes.colnames), 5)

The second column of ko_genes.data contains gene identifiers. Pass it to kegg_get with :aaseq or :ntseq to prepare input for a multiple sequence alignment.

6. Download a pathway map

The :image option returns the PNG bytes of a pathway map, which you can write to disk and open with your favourite image viewer or Images.jl:

img = KEGGAPI.kegg_get("map00520", :image)
@assert img.data isa Vector{UInt8} && !isempty(img.data)
path = tempname()
bytes_written = open(path, "w") do io
    write(io, img.data)
end
rm(path)
bytes_written == length(img.data)

true