dash_bio.Circos Examples and Reference

see Circos in action.

Circos

An example of a default Circos layout with heatmap or chords tracks.

Graph type:
Event data:
import json
import urllib.request as urlreq
import dash
from dash.dependencies import Input, Output, State
import dash_bio as dashbio
from dash import html, dcc


app = dash.Dash(__name__)

data = urlreq.urlopen(
    "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

app.layout = html.Div(
    [
        dashbio.Circos(
            id="my-dashbio-default-circos",
            layout=circos_graph_data["GRCh37"],
            selectEvent={"0": "hover"},
            tracks=[
                {
                    "type": "CHORDS",
                    "data": circos_graph_data["chords"],
                    "config": {
                        "tooltipContent": {
                            "source": "source",
                            "sourceID": "id",
                            "target": "target",
                            "targetID": "id",
                            "targetEnd": "end",
                        }
                    },
                }
            ],
        ),
        "Graph type:",
        dcc.Dropdown(
            id="histogram-chords-default-circos",
            options=[{"label": x, "value": x} for x in ["histogram", "chords"]],
            value="chords",
        ),
        "Event data:",
        html.Div(id="default-circos-output"),
    ]
)


@app.callback(
    Output("default-circos-output", "children"),
    Input("my-dashbio-default-circos", "eventDatum"),
)
def update_output(value):
    if value is not None:
        return [html.Div("{}: {}".format(v.title(), value[v])) for v in value.keys()]
    return "There are no event data. Hover over a data point to get more information."


@app.callback(
    Output("my-dashbio-default-circos", "tracks"),
    Input("histogram-chords-default-circos", "value"),
    State("my-dashbio-default-circos", "tracks"),
)
def change_graph_type(value, current):
    if value == "histogram":
        current[0].update(data=circos_graph_data["histogram"], type="HISTOGRAM")

    elif value == "chords":
        current[0].update(
            data=circos_graph_data["chords"],
            type="CHORDS",
            config={
                "tooltipContent": {
                    "source": "source",
                    "sourceID": "id",
                    "target": "target",
                    "targetID": "id",
                    "targetEnd": "end",
                }
            },
        )
    return current


if __name__ == "__main__":
    app.run_server(debug=True)

Customization

Layout

Configure layout’s inner, outer and corner radii, labels and ticks.

import json
import urllib.request as urlreq
import dash_bio as dashbio

data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

layout_config = {
    "innerRadius": 100,
    "outerRadius": 200,
    "cornerRadius": 4,
    "labels": {
        "size": 10,
        "color": "#4d4d4d",
    },
    "ticks": {
        "color": "#4d4d4d",
        "labelColor": "#4d4d4d",
        "spacing": 10000000,
        "labelSuffix": "Mb",
        "labelDenominator": 1000000,
        "labelSize": 10,
    },
}

dashbio.Circos(layout=circos_graph_data["GRCh37"], config=layout_config)

Chords

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

layout_config = {
    "labels": {
        "size": 10,
        "color": "#4d4d4d",
    },
    "ticks": {
        "color": "#4d4d4d",
        "labelColor": "#4d4d4d",
        "spacing": 10000000,
        "labelSuffix": "Mb",
        "labelDenominator": 1000000,
        "labelSize": 10,
    },
}

chords_config = {"color": "RdYlBu", "opacity": 0.8}

dashbio.Circos(
    layout=circos_graph_data["GRCh37"],
    config=layout_config,
    tracks=[
        {"type": "CHORDS", "data": circos_graph_data["chords"], "config": chords_config}
    ],
)

Data format:

data = [
  {
    "source": {
      "id": "chr19",
      "start": 22186054,
      "end": 36186054
    },
    "target": {
      "id": "chr17",
      "start": 21478117,
      "end": 85478117
    },
  },
  ...
]

Optionally each datum can define a value attribute to draw colored ribbons with color palettes.

Configuration options:

color, logScale, logScaleBase, max, min, opacity, radius, tooltipContent, zIndex

Heatmap

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

layout_config = {
    "labels": {"display": False},
    "ticks": {
        "color": "#4d4d4d",
        "labelColor": "#4d4d4d",
        "spacing": 10000000,
        "labelSuffix": "Mb",
        "labelDenominator": 1000000,
        "labelSize": 10,
    },
}

heatmap_config = {"innerRadius": 250, "outerRadius": 300, "color": "Greens"}

dashbio.Circos(
    layout=circos_graph_data["GRCh37"],
    config=layout_config,
    tracks=[
        {
            "type": "HEATMAP",
            "data": circos_graph_data["histogram"],
            "config": heatmap_config,
        }
    ],
)

Data format:

data = [
  {
    "block_id": "chr1",
    "start": 0,
    "end": 9999999,
    "value": 234
  },
  ...
]

Configuration options:

color, innerRadius, logScale, logScaleBase, max, min, outerRadius, tooltipContent

Highlight

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

layout_config = {
    "labels": {"display": False},
    "ticks": {
        "color": "#4d4d4d",
        "labelColor": "#4d4d4d",
        "spacing": 10000000,
        "labelSuffix": "Mb",
        "labelDenominator": 1000000,
        "labelSize": 10,
    },
}

highlight_config = {
    "innerRadius": 250,
    "outerRadius": 300,
    "color": {"name": "gieStain"},
}

dashbio.Circos(
    layout=circos_graph_data["GRCh37"],
    config=layout_config,
    tracks=[
        {
            "type": "HIGHLIGHT",
            "data": circos_graph_data["cytobands"],
            "config": highlight_config,
        }
    ],
)

Data format:

data = [
  {
    "block_id": "chr1",
    "start": 0,
    "end": 9999999,
    "gieStain": "rgb(200,200,200)" # custom key with CSS color code
    # use it in 'color' configuration option like this: { 'color': { 'name': 'gieStain' } } to highlight different parts of the track
  },
  ...
]

Configuration options:

color, innerRadius, logScale, logScaleBase, max, min, outerRadius, strokeColor, strokeWidth, opacity, tooltipContent

Histogram

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

layout_config = {
    "labels": {
        "size": 10,
        "color": "#4d4d4d",
    },
    "ticks": {"display": False},
}

tracks_config = {"innerRadius": 300, "outerRadius": 400, "color": "OrRd"}

dashbio.Circos(
    layout=circos_graph_data["GRCh37"],
    config=layout_config,
    tracks=[
        {
            "type": "HISTOGRAM",
            "data": circos_graph_data["histogram"],
            "config": tracks_config,
        }
    ],
)

Data format:

data = [
  {
    "block_id": "chr1",
    "start": 0,
    "end": 9999999,
    "value": 234
  },
  ...
]

Configuration options:

axes, color, innerRadius, logScale, logScaleBase, max, min, opacity, outerRadius, tooltipContent, zIndex

Line

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

GRCh37_123 = list(
    filter(lambda x: x["id"] in ["chr1", "chr2", "chr3"], circos_graph_data["GRCh37"])
)

layout_config = {"labels": {"display": False}, "ticks": {"display": False}}

snp_250_config = {
    "innerRadius": 0.5,
    "outerRadius": 0.8,
    "maxGap": 1000000,
    "min": 0,
    "max": 0.015,
    "color": "#222222",
    "axes": [{"spacing": 0.001, "thickness": 1, "color": "#666666"}],
    "backgrounds": [
        {"start": 0, "end": 0.002, "color": "#f44336", "opacity": 0.5},
        {"start": 0.006, "end": 0.015, "color": "#4caf50", "opacity": 0.5},
    ],
}

snp_config = {
    "innerRadius": 1.01,
    "outerRadius": 1.15,
    "maxGap": 1000000,
    "min": 0,
    "max": 0.015,
    "color": "#222222",
    "axes": [
        {"position": 0.002, "color": "#f44336"},
        {"position": 0.006, "color": "#4caf50"},
    ],
}

snp_1m_config = {
    "innerRadius": 1.01,
    "outerRadius": 1.15,
    "maxGap": 1000000,
    "min": 0,
    "max": 0.015,
    "color": "#f44336",
}

snp_in_config = {
    "innerRadius": 0.85,
    "outerRadius": 0.95,
    "maxGap": 1000000,
    "direction": "in",
    "min": 0,
    "max": 0.015,
    "color": "#222222",
    "axes": [
        {"position": 0.01, "color": "#4caf50"},
        {"position": 0.008, "color": "#4caf50"},
        {"position": 0.006, "color": "#4caf50"},
        {"position": 0.002, "color": "#f44336"},
    ],
}

snp_1m_in_config = {
    "innerRadius": 0.85,
    "outerRadius": 0.95,
    "maxGap": 100000000,
    "direction": "in",
    "min": 0,
    "max": 0.015,
    "color": "#f44336",
}

dashbio.Circos(
    layout=GRCh37_123,
    config=layout_config,
    tracks=[
        {
            "id": "snp250",
            "type": "LINE",
            "data": circos_graph_data["snp250"],
            "config": snp_250_config,
        },
        {
            "id": "snp1m",
            "type": "LINE",
            "data": circos_graph_data["snp1m"],
            "config": snp_1m_config,
        },
        {
            "id": "snp",
            "type": "LINE",
            "data": circos_graph_data["snp"],
            "config": snp_config,
        },
        {
            "id": "snpIn",
            "type": "LINE",
            "data": circos_graph_data["snp"],
            "config": snp_in_config,
        },
        {
            "id": "snp1mIn",
            "type": "LINE",
            "data": circos_graph_data["snp1m"],
            "config": snp_1m_in_config,
        },
    ],
)

Data format:

data = [
  {
      "block_id": "chr1"
      "position": 499999.5,
      "value": 0.006405,
  },
  ...
]

Configuration options:

axes, backgrounds, color, direction, fill, fillColor, innerRadius, logScale, logScaleBase, max, min, opacity, outerRadius, strokeColor, strokeWidth, zIndex

Scatter

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

GRCh37_123 = list(
    filter(lambda x: x["id"] in ["chr1", "chr2", "chr3"], circos_graph_data["GRCh37"])
)

layout_config = {"labels": {"display": False}, "ticks": {"display": False}}

snp_250_config = {
    "innerRadius": 0.5,
    "outerRadius": 0.8,
    "min": 0,
    "max": 0.015,
    "color": "#222222",
    "size": 2,
    "strokeWidth": 0,
    "axes": [{"spacing": 0.001, "thickness": 1, "color": "#666666"}],
    "backgrounds": [
        {"start": 0, "end": 0.002, "color": "#f44336", "opacity": 0.5},
        {"start": 0.006, "end": 0.015, "color": "#4caf50", "opacity": 0.5},
    ],
}

snp_1m_config = {
    "innerRadius": 1.01,
    "outerRadius": 1.10,
    "maxGap": 1000000,
    "min": 0,
    "max": 0.01,
    "color": "#f44336",
    "size": 2,
    "strokeWidth": 0,
    "axes": [{"spacing": 0.002, "thickness": 1, "color": "#666666"}],
}

snp_config = {
    "innerRadius": 1.01,
    "outerRadius": 1.15,
    "maxGap": 1000000,
    "min": 0,
    "max": 0.015,
    "color": "#222222",
    "size": 2,
    "strokeWidth": 0,
    "axes": [
        {"position": 0.002, "color": "#f44336"},
        {"position": 0.006, "color": "#4caf50"},
    ],
}

snp_in_config = {
    "innerRadius": 0.85,
    "outerRadius": 0.95,
    "maxGap": 1000000,
    "direction": "in",
    "min": 0,
    "max": 0.015,
    "color": "#222222",
    "size": 2,
    "strokeWidth": 0,
    "axes": [
        {"position": 0.01, "color": "#4caf50"},
        {"position": 0.008, "color": "#4caf50"},
        {"position": 0.006, "color": "#4caf50"},
        {"position": 0.002, "color": "#f44336"},
    ],
}

snp_1m_in_config = {
    "innerRadius": 0.85,
    "outerRadius": 0.95,
    "maxGap": 100000000,
    "direction": "in",
    "min": 0,
    "max": 0.015,
    "color": "#f44336",
    "size": 2,
    "strokeWidth": 0,
}

dashbio.Circos(
    layout=GRCh37_123,
    config=layout_config,
    tracks=[
        {
            "id": "snp250",
            "type": "SCATTER",
            "data": circos_graph_data["snp250"],
            "config": snp_250_config,
        },
        {
            "id": "snp1m",
            "type": "SCATTER",
            "data": circos_graph_data["snp1m"],
            "config": snp_1m_config,
        },
        {
            "id": "snp",
            "type": "SCATTER",
            "data": circos_graph_data["snp"],
            "config": snp_config,
        },
        {
            "id": "snpIn",
            "type": "SCATTER",
            "data": circos_graph_data["snp"],
            "config": snp_in_config,
        },
        {
            "id": "snp1mIn",
            "type": "SCATTER",
            "data": circos_graph_data["snp1m"],
            "config": snp_1m_in_config,
        },
    ],
)

Data format:

data = [
  {
      "block_id": "chr1"
      "position": 499999.5,
      "value": 0.006405,
  },
  ...
]

Configuration options:

axes, backgrounds, color, direction, fill, innerRadius, logScale, logScaleBase, max, min, opacity, outerRadius, shape, size, strokeColor, strokeWidth, zIndex

Stack

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

GRCh37_9 = [{"id": "chr9", "len": 8000000, "label": "chr9", "color": "#FFCC00"}]

layout_config = {"labels": {"display": False}, "ticks": {"display": False}}

stack_config = {
    "innerRadius": 0.7,
    "outerRadius": 1,
    "thickness": 4,
    "margin": 800000,
    "direction": "out",
    "color": {"name": "color"},
    "strokeWidth": 0,
}

dashbio.Circos(
    layout=GRCh37_9,
    config=layout_config,
    tracks=[
        {"type": "STACK", "data": circos_graph_data["stack"], "config": stack_config}
    ],
)

Data format:

data = [
  {
    "block_id": "chr1",
    "start": 0,
    "end": 9999999,
  },
  ...
]

Configuration options:

axes, backgrounds, color, direction, fill, innerRadius, logScale, logScaleBase, margin, max, min, opacity, outerRadius, radialMargin, strokeColor, strokeWidth, thickness, tooltipContent

Text

import json
import urllib.request as urlreq
import dash_bio as dashbio


data = urlreq.urlopen(
  "https://git.io/circos_graph_data.json"
).read().decode("utf-8")

circos_graph_data = json.loads(data)

GRCh37_1 = circos_graph_data["GRCh37"][:1]
cytobands_1 = list(
    map(
        lambda x: {**x, **{"value": x["name"], "position": (x["start"] + x["end"]) / 2}},
        filter(lambda x: x["block_id"] in ["chr1"], circos_graph_data["cytobands"]),
    )
)

layout_config = {
    "innerRadius": 275,
    "outerRadius": 300,
    "labels": {"display": False},
    "ticks": {"display": False},
}

text_config = {
    "innerRadius": 1.02,
    "style": {
        "font-size": 12,
    },
}


highlight_config = {
    "innerRadius": 275,
    "outerRadius": 300,
    "color": {"name": "gieStain"},
}

dashbio.Circos(
    layout=GRCh37_1,
    config=layout_config,
    tracks=[
        {"type": "TEXT", "data": cytobands_1, "config": text_config},
        {"type": "HIGHLIGHT", "data": cytobands_1, "config": highlight_config},
    ],
)

Data format:

data = [
  {
    "block_id": "chr1",
    "position": 1150000,
    "value": "p36.33",
  },
  ...
]

Configuration options:

innerRadius, outerRadius, style

Tracks configuration options reference

axes

A list of dicts with axes configurations.

Styling options:
- color (default: #d3d3d3)
- thickness (in pixel, default: 1)
- opacity (value between 0 and 1, default: track opacity)

Positioning options:
- position (generate a single axis at a given position; value between the min and max values of the track)
- spacing (generate a range of evenly spaced axes)
- start (optional property used when spacing is defined; value between the min and max values of the track; default: max value of the track)
- end (optional property used when spacing is defined; value between the min and max values of the track; default: max value of the track)

Example:

{
  'axes': [
    {
      'color': 'red',
      'position': 4,
      'opacity': 0.3
    },
    {
      'color': 'red',
      'spacing': 2,
      'end': 4
    },
    {
      'color': 'green',
      'spacing': 1,
      'start': 4,
      'end': 16,
      'thickness': 1
    }
  ]
}

backgrounds

A list of dicts with background configurations.

Styling options:
- color (default: #d3d3d3)
- opacity (between 0 and 1, default: track’s opacity)

Positioning options:
- start (value between the min and max values of the track; default: min value of the track)
- end (value between the min and max values of the track; default: max value of the track)

Example:

{
  backgrounds: [
    {
      start: 0.006,
      color: '#4caf50',
      opacity: 0.1
    },
    {
      start: 0.002,
      end: 0.006,
      color: '#d3d3d3',
      opacity: 0.1
    },
    {
      end: 0.002,
      color: '#f44336',
      opacity: 0.1
    }
  ]
}

color

The color attribute can be either:

Available palette names: BrBG, PRGn, PiYG, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral, Blues, Greens, Greys, Oranges, Purples, Reds, BuGn, BuPu, GnBu, OrRd, PuBuGn, PuBu, PuRd, RdPu, YlGnBu, YlGn, YlOrBr, YlOrRd (from d3-scale-chromatic)

When using pallete name, the color will be computed dynamically according to the track data value field.

If you prefix the palette name with a - (e.g -BrBG), the palette will be reversed.

{
  'color': {
    'name': 'property_of_track_data_element'
    # value of `name` should be the property name of track's data elements, holding CSS color value
  }
}

See example usage in highlight track configuration.

direction

in or out. Default: out. For stack you can also use center.

fill

bool

fillColor

CSS color code, e.g: #d3d3d3, blue, rgb(0, 0, 0)

innerRadius and outerRadius

For layout configuration innerRadius and outerRadius values are always interpreted as a number of pixels.

For track configuration:

If innerRadius and outerRadius are between 0 and 1, the value is interpreted as a fraction of the innerRadius of the layout.

If innerRadius and outerRadius are between 1 and 10, the value is interpreted as a fraction of the outerRadius of the layout.

Otherwise it is interpreted as a number of pixels.

logScale

bool. Default is False.

logScaleBase

The log base if logScale is True. Default is Math.E.

max and min

The default min and max values are computed automatically based on the dataset. You can override these values by specifying a min or max attribute in the configuration.

opacity

float between 0 and 1. Default is 1.

radius

In the chords configuration you can specify a radius parameter.

If the value is between 0 and 1, it is interpreted as a fraction of the innerRadius of the layout.

If the value is greater than 1, it is interpreted as a number of pixels.

Default value is the innerRadius of the layout.

shape

One of:
- circle
- cross
- diamond
- square
- triangle
- star
- wye

strokeColor

CSS color code, e.g: #d3d3d3, blue, rgb(0, 0, 0)

strokeWidth

int

style

dict with CSS styles.

thickness

int

tooltipContent

Available options:

#  display all key-value pairs of track's data elements
{
  'tooltipContent': {
      'name': 'all',
  }
}
# display value of any property specified on track's data elements
{
  'tooltipContent': {
      'name': 'property_name',
  }
}
# display tooltip content in form: d[source] + ' > ' + d[target] + ': ' + d[targetEnd]
# (e.g. d["block_id"] + ' > ' + d["position"] + ': ' + d["value"])
{
  'tooltipContent': {
    "source": "block_id",
    "target": "position",
    "targetEnd": "value"
  }
}

For chords track with nested dicts:

# display tooltip content in form: d[source][sourceID] + ' > ' + d[target][targetID] + ': ' d[target][targetEnd]
# (e.g. d["source"]["id"] + ' > ' + d["target"]["id"] + ': ' + d["target"]["end"])
{
  'tooltipContent': {
      'source': 'source',
      'sourceID': 'id',
      'target': 'target',
      'targetID': 'id',
      'targetEnd': 'end'
  }
}

zIndex

int. Positions tracks along the z-axis. The higher the number, the more on top a given track will appear.

Circos Properties

Access this documentation in your Python terminal with:
```python

help(dash_bio.Circos)
```

Our recommended IDE for writing Dash apps is Dash Enterprise’s
Data Science Workspaces,
which has typeahead support for Dash Component Properties.
Find out if your company is using
Dash Enterprise
.

enableDownloadSVG (boolean; optional):
Allow for an SVG snapshot of the Circos graph to be downloaded.

enableZoomPan (boolean; optional):
Allow for zooming and panning the Circos graph.

id (string; optional):
The ID of the component to be used in Dash callbacks.

style (dict; optional):
The CSS styling of the div wrapping the component.

eventDatum (dict; optional):
A Dash prop that returns data on clicking or hovering of the tracks,
depending on what is specified for prop “selectEvent”.

selectEvent (dict; optional):
A dictionary used to choose whether tracks should return data on
click, hover, or both, with the dash prop “eventDatum”. The keys of
the dictionary represent the index of the list specified for “tracks”.
Ex: selectEvent={ “0”: “hover”, “1”: “click”,
“2”: “both” },.

layout (list of dicts; required):
Data used to draw Circos layout blocks.

layout is a list of dicts with keys:

config (dict; optional):
Configuration options for the graph layout.

config is a dict with keys:

size (number; default 800):
The overall size of the SVG container holding the graph. Set on
initilization and unchangeable thereafter.

tracks (list of dicts; optional):
A list of tracks displayed on top of the base Circos layout.

tracks is a list of dicts with keys:

loading_state (dict; optional):
Object that holds the loading state object coming from dash-renderer.

loading_state is a dict with keys:

Example Data