KeggMapWizard

Warning Using this tool may require a KEGG subscription!

This script downloads KEGG REST data, KEGG configs and KEGG PNGs and converts them into SVG maps which can be processed dynamically using modern browsers.

I included a simple JavaScript library that enables coloring the maps. It requires

jQuery
chroma.js to calculate color gradients
html2canvas to render the SVGs as PNGs

Python

Creating the SVGs

Install the requirements. pip install poetry && poetry install

Set the environment variable KEGG_MAP_WIZARD_DATA to where you want data to be downloaded to.

export KEGG_MAP_WIZARD_DATA='/path/to/desired/download/location'

or in Python:

import os

os.environ['KEGG_MAP_WIZARD_DATA'] = '/path/to/desired/download/location'

In a Python 3.9 console, type:

from kegg_map_wizard import KeggMapWizard, KeggMap, KeggShape, KeggAnnotation, ColorMaker

kmw = KeggMapWizard(orgs=['ko', 'rn', 'ec'])  # merge ko, rn and ec annotations
kmw.download_maps()  # this will download all available KEGG maps
kmw.download_maps(map_ids=['00400'], reload=True)  # this will only download this specific KEGG map

# Create KeggMap object
kegg_map = kmw.create_map('00400')

# Create SVG
svg = kegg_map.svg()

# Save SVG
with open('/path/to/outfile.svg', 'w') as f:
    f.write(svg)

By default, all shapes are transparent. Below are some examples on how to apply colors:

def custom_color_function(shape: KeggShape):
    '''Color all shapes red'''
    return 'red'


def custom_color_function(shape: KeggShape):
    '''Color only shapes with the annotation K01623 red'''
    if ('K', 'K01623') in shape.annotations_dict:
        return 'red'
    else:
        return 'transparent'


def custom_color_function(shape: KeggShape):
    '''Color all shapes with 4 sequential colors (yellow, red, blue, green)'''
    shape.definition = ColorMaker.svg_gradient(
        colors=['yellow', 'red', 'blue', 'green'],
        id=shape.hash,
        x1=shape.bbox.x1,
        x2=shape.bbox.x2
    )
    return f'url(#{shape.hash})'


# Create svg using the custom_color_function
svg = kegg_map.svg(color_function=custom_color_function)

The last custom_color_function results in this:

The gradient is defined in shape.definition and looks like this:

<linearGradient id="{shape.hash}" gradientUnits="userSpaceOnUse" x1="{shape.bbox.x1}" x2="{shape.bbox.x2}">
    <stop offset="25%" stop-color="yellow"></stop><stop offset="25%" stop-color="red"></stop>
    <stop offset="50%" stop-color="red"></stop><stop offset="50%" stop-color="blue"></stop>
    <stop offset="75%" stop-color="blue"></stop><stop offset="75%" stop-color="green"></stop>
</linearGradient>

Testing and colouring SVGs

To test the maps, run a simple http server in the kegg_map_wizard: python -m http.server 8000

Then open http://localhost:8000/kegg_map_wizard/html/map_tester.html

JavaScript

Shapes can not just be colored via Python, but also via JavaScript in the web browser.

For an example, see how this library is used in OpenGenomeBrowser .

Required SVG format

The svg should have a title attribute. Example:

<svg
        title='Phenylalanine, tyrosine and tryptophan biosynthesis'
        version='1.1' baseProfile='full' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink'
        <!-- other attributes -->
        >

Each enzyme in the SVG needs to belong to the class shape and have the data-annotations-attribute. Example:

<circle cx='978' cy='930' r='4' fill='transparent'  <!-- Must not be circle, can be any other SVG element -->
        title='C00296 (Quinate)'  <!-- will tooltip -->
        class='shape compound'  <!-- only class 'shape' is required -->
        data-annotations='[{"description": "L-Ectoine", "name": "C06231", "type": "KEGG Compound"}]'>  <!-- see below -->
        />

The data-annotations-attribute tells the KeggMapWizard library which annotations are behind the shape.

Example:

[
  {
    "description": "L-Ectoine",
    "name": "C06231",
    "type": "KEGG Compound"
  }
]

How access the properties using JavaScript/jQuery

append a click event listener to all shapes:

$('.shape').click(function (event) {
    showMapMenu(event, this)
})

loop over all shapes:

$(".shape").each(function () {
    // do something
    console.log($(this).attr('title'))  // or 'data-original-title'
})

read data-annotations into a variable, loop over annotations, save the changes back into data-annotations:

let annotations = $(shape).data('annotations')  // read
annotations.forEach(function (annotation, index) {
    // do something
    console.log(annotation['name'])
})
$(shape).data('annotations', annotations)  // save changes

How to use PathwaySvgLib functions

highlight specific annotations:

highlightBinary(
    color = "green",
    annotations_to_highlight = ["R01518", "K15778", "K22473"]
)

color using continuous numbers:

highlightContinuous(
    svg = document.getElementById('custom-kegg').firstChild,
    annotation_to_number = {R01518: 0, K15778: 0.5, K22473: 1},
    colors = ['yellow', 'red']
)

color organisms with gradient:

highlightOrganisms(
    svg = document.getElementById('some-svg'),
    organisms = {
        "Organism 1": ["R01518", "K15778", "K22473"],
        "Organism 2": ["K02446", "R00959", "C01172"],
        "Organism 3": ["R01518", "K00129", "EC:2.7.1.147"]
    },
    colors = ['yellow', 'red']
)

color groups of organisms with gradient:

highlightGroupsOfOrganisms(
    svg = document.getElementById('some-svg'),
    groupsOfOrganisms = {
        Grp1: {
            "Organism 1": ["R01518", "K15778", "K22473"],
            "Organism 2": ["K02446", "R00959", "C01172"],
            "Organism 3": ["R01518", "K00129", "EC:2.7.1.147"]
        },
        Grp2: {
            "Organism 4": ["R01518", "K15778", "K22473"],
            "Organism 5": ["K02446", "R00959", "C01172"]
        },
    }
)

The enzyme boxes will be separated into as many areas as there are groups. Group 1 organisms color the leftmost area, group 2 the second from the left, etc.

save map as PNG

saveDivAsPng('id-of-svg')

MrTomRod / kegg-map-wizard