Use the latest version of Circos and read Circos best practices—these list recent important changes and identify sources of common problems.

If you are having trouble, post your issue to the Circos Google Group and include all files and detailed error logs. Please do not email me directly unless it is urgent—you are much more likely to receive a timely reply from the group.

Don't know what question to ask? Read Points of View: Visualizing Biological Data by Bang Wong, myself and invited authors from the Points of View series.

7 — 2D Data Tracks

5. Heat maps

The heatmap track is a feature that combines the utility of highlights and a 2D plot. In this track, regions of the genome are assigned a value (e.g. density of genes) and are shown as wedges whose color is a function of the value. The regions do not need to be of fixed size, and larger regions are drawn before smaller ones (this happens automatically) to avoid occlusion.

Circos will map the value of each region to a color range defined in the color parameter. Unlike other tracks, the heatmap expects a list of colors. The list can be explicitly defined in the track block, or you can use the name of a color list previously defined in <colors>. For more details about color lists, see below, and the Configuration File section.

A typical heatmap block looks like this

type    = heatmap
file    = data/6/snp.number.1mb.txt
# color list
color   = spectral-5-div
r1      = 0.95r
r0      = 0.80r

The data format for the heatmap is the same as for other plots: chr, start, end, value, and a list of optional parameters.

hs7 36975000 36999999 33
hs7 37000000 37024999 50
hs7 37025000 37049999 60 color=blue
hs7 37050000 37074999 44

Since line plots, histograms and heatmaps share the same data format, you can chnage the type of plot without altering the data file.

color mapping

default mapping

If min and max are not defined, the color of the data point will be assigned based on its value as follows

color_index = num_colors * (value-min)/(max-min)

If you explicitly define min and max (one or both), then the color value will be assigned using these values rather than the data's statistics. Values falling outside the specified min or max range will be assigned first/last colors in the list, as appropriate.

Color assignment is applied to a value range [x,y).

The default mapping corresponds to color_mapping=0. You don't need to set this parameter if you want the default mapping.

alternate mappings

There are two other color mapping schemes. They are illustrated in this image. These methods are design for cases where you set min and max values.

A heatmap with n colors will map the colors onto the range [min,max] and areas outside the range as follows.

 colors:  1,2,3,...,m,n   where m=n-1

 color_mapping        min                 max
             0      0  |  001122 ... mmnn  |  n  divided uniformly
             1      0  |  01122  ... mmn   |  n  division at min/max boundary 1/2 size of others
             2      0  |  112233 ... mm    |  n  divided uniformly, 0,n reserved for [,min] and [max,]

Notice that for the default color_mapping=0 if you have only 2 colors then the

The last scheme color_mapping=2 is useful when you want to reserve the first and last colors to regions of the heatmap below/above the plot min and max values. Typical use of this would be

color         = black,spectral-5-div,grey
color_mapping = 2

where black would be assigned to values <min and grey to values ≥max.

If you want to precisely control mapping then use rules.

condition     = var(value) < 0.5
color         = black
condition     = var(value) > 9.5
color         = grey

non-linear mapping

By default, the mapping between value and color is done linearly using the expression. If you set scale_log_base, the mapping will be logarithmic. Now, instead of index i being mapped to values from x_i to x_j, it is mapped onto

min + (x_i-min)/(max-min) ^ 1/scale_log_base ... min + (x_j-min)/(max-min) ^ 1/scale_log_base

If scale_log_base<1, the dynamic range of color mapping of small values will be increased. If scale_log_base>1, then dynamic range of large values will be increased.

The scale_log_base parameter is useful when data are skewed.

using color lists

Heatmaps are best used with predefined color lists. To learn how to define lists, see Configuration File section.

Instead of explicitly listing colors for the heatmap, use the name of the color list for the color parameter.

For example, the spectral-11-div list was defined in etc/brewer.conf. It is a list of the 11-color spectral diverging Brewer palette. To use the list,

color = spectral-11-div

You can combine lists to extend the color range of the heat map. Below the yellow-orange-red palette (a reversed version) is concatenated with the yellow-green-blue palette.

color = ylorrd-9-seq-rev,ylgnbu-9-seq

You can also combine colors and lists

color = black,ylorrd-9-seq-rev,white,ylgnbu-9-seq,grey

pattern fills

In addition to setting the color of a value, you can specify a pattern fill. Think of the pattern as an independent encoding—analogous to color and color_mapping you can use pattern and pattern_mapping.

For example, to make values in the first half of their range filled with vertical lines and as horizontal lines in the second half,

pattern = vline,hline

To make regions with values <min filled with vertical lines and those with ≥max as horizontal lines

pattern         = vline,solid,hline
pattern_mapping = 2

For a list of patterns, see etc/patterns.conf. You can always make your own. Look at the pattern images in etc/tiles.

color legend

Circos doesn't yet draw color legends. You can get a list of the color encoding by using -debug_group legend.

≥ circos -conf ... -debug_group legend
debuggroup legend 3.01s track_0  -inf 2000.000   inf 0 spectral-9-div-1 213,62,79
debuggroup legend 3.01s track_0 2000.000 29555.556 27555.556 0 spectral-9-div-1 213,62,79
debuggroup legend 3.01s track_0 29555.556 57111.111 27555.556 1 spectral-9-div-2 244,109,67
debuggroup legend 3.01s track_0 57111.111 84666.667 27555.556 2 spectral-9-div-3 253,174,97
debuggroup legend 3.01s track_0 84666.667 112222.222 27555.556 3 spectral-9-div-4 254,224,139
debuggroup legend 3.01s track_0 112222.222 139777.778 27555.556 4 spectral-9-div-5 255,255,191
debuggroup legend 3.01s track_0 139777.778 167333.333 27555.556 5 spectral-9-div-6 230,245,152
debuggroup legend 3.01s track_0 167333.333 194888.889 27555.556 6 spectral-9-div-7 171,221,164
debuggroup legend 3.01s track_0 194888.889 222444.444 27555.556 7 spectral-9-div-8 102,194,165
debuggroup legend 3.01s track_0 222444.444 250000.000 27555.556 8 spectral-9-div-9 50,136,189
debuggroup legend 3.01s track_0 250000.000  +inf   inf 8 spectral-9-div-9 50,136,189
debuggroup legend 6.73s track_8  -inf 0.000   inf 0 hline 0,0,0
debuggroup legend 6.73s track_8 0.000 10.000 10.000 1 solid 0,0,0
debuggroup legend 6.73s track_8 10.000  +inf   inf 2 vline 0,0,0
debuggroup legend 6.96s track_9  -inf 2.000   inf 0 black 0,0,0