kegg-map-kit

Colour KEGG pathway maps from a table of KEGG Ontology (KO) identifiers and render the result as SVG. A scriptable, SVG-producing counterpart to the KEGG Mapper Color tool.

Zero runtime dependencies — Python 3.10+ and the standard library.

Example

Glycolysis (ko00010) coloured from twelve values. Each box carries its EC number redrawn on top of an opaque fill, so the caption stays legible at any colour; the value is printed beneath; KO boxes with no data are grey; and the colorbar is pinned to a fixed range so separate maps stay comparable.

kegg-map-kit ko00010 -i examples/demo.tsv -o glycolysis.svg \
    --cmap coolwarm --vmin -2.5 --vmax 2.5 \
    --box-labels ec --unmapped-color '#ececec' --label-values

The numbers in examples/demo.tsv are synthetic. examples/glycolysis_vector.svg is the same data through --mode vector: no bitmap at all, so it rasterises losslessly at any resolution, at the cost of KEGG's arrows and decorations.

Install

uv tool install kegg-map-kit
# or
pip install kegg-map-kit

Use

kegg-map-kit ko00010 -i data.tsv -o map.svg

data.tsv holds a KO identifier per line, followed by either colours or numbers:

K00844	#ff0000
K01810	blue
K00845	#00ff00,#000000

The third line uses KEGG Mapper's bg,fg syntax: the second colour sets the box's label colour in --mode vector. Fields may be separated by tabs, commas or spaces, so a file written for KEGG Mapper works unchanged. Only whole lines beginning with # are treated as comments; there are no trailing comments.

or values, which are mapped through a colormap and get a legend:

K00844	2.0	1.4
K01810	-1.5	-0.2

Several columns, or several KOs sharing one box, split that box into vertical slices (up to 12).

Options

Coloured boxes carry hover text and link to their KEGG entry page.

KEGG data is cached indefinitely under --cache; delete that directory to refresh.

Exit codes

Exit 2 means the network, and only the network, so a script can retry on 2 and give up on 1.

Scope

v0.1.0 handles KO-level maps (ko#####) and colours rectangle entries only. Compounds, organism-specific gene IDs, and the line-based global maps such as ko01100 are not coloured.

Licence

MIT. KEGG data is © Kanehisa Laboratories and is subject to the KEGG terms of use; this tool only retrieves and renders it.