Circos

Demo: nicgirault.github.io/circosJS/demo

table of contents

• Introduction
• Installation
• Layout
• Tracks
  • Chords
  • Heatmap
  • Highlight
  • Histogram
  • Line
  • Scatter
  • Stack
  • Text
• Configuration Attributes
  • innerRadius
  • outerRadius
  • min
  • max
  • color
  • axes
  • showAxesTooltip

Introduction

Circos is a javascript library to easily build interactive graphs in a circular layout. It's based on d3.js. It aims to be a javascript version of the Circos software.

You should consider using Circos to show:

• relationships between entities
• periodical data

<p align="center"> <img src="doc/temperatures.png" width="60%" alt="temperatures"> <br/> <i>Average temperatures in Paris from 2007 (inner) to 2014 (outer). The circular layout highlights seasonal effect.</i> </p>

Installation

If you don't know what is npm you can skip this step and get started with this canvas. Otherwise:

npm install --save circos

Layout

To instantiate a new circos:

var myCircos = new Circos({
    container: '#chart',
    width: 500,
    height: 500,
});

A circos graph is based on a circular axis layout. Data tracks appear inside and/or outside the circular layout.

In order to place data on the circos graph, you must first specify the layout.

myCircos.layout(data, configuration);

The first argument of the layout function is a configuration object that control the format of the layout.

Here are the default parameters for a layout:

var configuration = {
  innerRadius: 250,
  outerRadius: 300,
  cornerRadius: 10,
  gap: 0.04, // in radian
  labels: {
    display: true,
    position: 'center',
    size: '14px',
    color: '#000000',
    radialOffset: 20,
  },
  ticks: {
    display: true,
    color: 'grey',
    spacing: 10000000,
    labels: true,
    labelSpacing: 10,
    labelSuffix: 'Mb',
    labelDenominator: 1000000,
    labelDisplay0: true,
    labelSize: '10px',
    labelColor: '#000000',
    labelFont: 'default',
    majorSpacing: 5,
    size: {
      minor: 2,
      major: 5,
    }
  },
  events: {}
}

The second argument of the layout function is an array of data that describe the layout regions. Each layout region must have an id and a length. You can also specify a color and a label.

var data = [
  { len: 31, color: "#8dd3c7", label: "January", id: "january" },
  { len: 28, color: "#ffffb3", label: "February", id: "february" },
  { len: 31, color: "#bebada", label: "March", id: "march" },
  { len: 30, color: "#fb8072", label: "April", id: "april" },
  { len: 31, color: "#80b1d3", label: "May", id: "may" },
  { len: 30, color: "#fdb462", label: "June", id: "june" },
  { len: 31, color: "#b3de69", label: "July", id: "july" },
  { len: 31, color: "#fccde5", label: "August", id: "august" },
  { len: 30, color: "#d9d9d9", label: "September", id: "september" },
  { len: 31, color: "#bc80bd", label: "October", id: "october" },
  { len: 30, color: "#ccebc5", label: "November", id: "november" },
  { len: 31, color: "#ffed6f", label: "December", id: "december" }
]

The id parameter will be used to place data points on the layout.

To visualize the result:

myCircos.render();

Tracks

A track is a series of data points.

To add a track to your graph you should write something like this:

myCircos.heatmap(
    'my-heatmap',
    data,
    {
        // your heatmap configuration (optional)
    },
);

This pattern is similar to all track types:

myCircos.trackType('track-id', data, configuration);

Note: The track name is used as a HTML class name so here are the format limitations.

• Must be unique.
• Should be slug style for simplicity, consistency and compatibility. Example: my-heatmap
• Lowercase, a-z, can contain digits, 0-9, can contain dash or dot but not start/end with them.
• Consecutive dashes or dots not allowed.
• 50 characters or less.

Chords

Chords tracks connect layout regions.

<p align="center"> <img src="doc/chords.png" width="60%" alt="chords"> <br/> <i>Some gene fusions in human karyotype (<a href="demo/chords.js">source</a>)</i> </p>

Data should looks like this:

var data = [
  {
    source: {
      id: 'january',
      start: 1,
      end: 12
    },
    target: {
      id: 'april',
      start: 18,
      end: 20
    }
  },
  {
    source: {
      id: 'february',
      start: 20,
      end: 28
    },
    target: {
      id: 'december',
      start: 1,
      end: 13
    }
  },
  ...
];

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

The available configuration fields are:

• color
• events
• opacity
• zIndex
• tooltipContent
• min
• max
• radius
• logScale
• logScaleBase

Heatmap

<p align="center"> <img src="doc/heatmap.png" width="60%" alt="heatmap"> <br/> <i>Electrical comsumption in France in 2014</i> </p>

To add a heatmap to your circos instance:

myCircos.heatmap('electrical-consumption', data, configuration);

Configuration:

{
  innerRadius: null,
  outerRadius: null,
  min: null,
  max: null,
  color: 'YlGnBu',
  logScale: false,
  tooltipContent: null,
  events: {}
}

Data format:

var data = [
  {
    block_id: 'january',
    start: 0,
    end: 1,
    value: 1368001
  },
  {
    block_id: 'january',
    start: 1,
    end: 2,
    value: 1458583
  },
  ...
]

Highlight

<p align="center"> <img src="doc/highlight.png" width="60%" alt="highlight"> <br/> <i>Human karyotype with cytobands highlighted (<a href="demo/highlight.js">source</a>)</i> </p>

To add a highlight to your circos instance:

myCircos.highlight('cytobands', data, configuration);

The minimal datum should have block_id, start and end attributes.

Configuration:

{
  innerRadius: null,
  outerRadius: null,
  min: null,
  max: null,
  color: 'd3d3d3',
  strokeColor: null,
  strokeWidth: 0,
  opacity: 1,
  logScale: false,
  tooltipContent: null,
  events: {}
}

Histogram

<p align="center"> <img src="doc/histogram.png" width="60%" alt="histogram"> <br/> <i>Genetic abnormalities in human stem cells (<a href="demo/histogram.js">source</a>)</i> </p>

Data should looks like this:

var data = [
    {
      block_id: 'january',
      start: 1,
      end: 10,
      value: 5
    }
];

The available configuration fields are:

• innerRadius
• outerRadius
• color
• opacity
• zIndex
• tooltipContent
• min
• max
• logScale
• logScaleBase
• axes
• events

Line

<p align="center"> <img src="doc/line.png" width="60%" alt="line"> <br/> <i>Some single nucleotide polymorphism on chromosomes 1, 2 and 3 (<a href="demo/line.js">source</a>)</i> </p>

myCircos.line('line1', data, configuration);

The minimal datum should have block_id, position and value attributes (see above tracks for more details).

The available configuration fields are:

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

Note: The tooltip option is not available for line track. To display a tooltip, you should superimpose an invisble scatter track (fill: false and strokeWidth: 0) and set a tooltip for this track.

Scatter

<p align="center"> <img src="doc/scatter.png" width="60%" alt="scatter"> <br/> <i><a href="demo/line.js">source</a></i> </p>

myCircos.scatter('scatter1', data, configuration);

The minimal datum should have block_id, position and value attributes (see above tracks for more details).

The available configuration fields are:

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

Stack

<p align="center"> <img src="doc/stack.png" width="60%" alt="stack"> <br/> <i><a href="demo/stack.js">source</a></i> </p>

myCircos.stack('stack', data, configuration);

The minimal datum should have block_id, start and end attributes (see above tracks for more details).

Configuration:

{
  innerRadius: null,
  outerRadius: null,
  min: null,
  max: null,
  color: '#fd6a62',
  strokeColor: '#d3d3d3',