Circos > Documentation > Tutorials > Recipes > Cortical Maps

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.

9 — Recipes

19. Cortical Maps

In this example I will show you how to create maps of the brain connectome using Circos — a connectogram. Images of this type have recently appeared in papers from the Van Horn group at UCLA.

Irimia A, Chambers MC, Torgerson CM et al. 2012 Patient-tailored connectomics visualization for the assessment of white matter atrophy in traumatic brain injury Frontiers in Neurology 3

Irimia A, Chambers MC, Torgerson CM et al. 2012 Circular representation of human cortical networks for subject and population-level connectomic visualization NeuroImage.

Van Horn JD, Irimia A, Torgerson CM et al. 2012 Mapping connectivity damage in the case of phineas gage PLoS One 7:e37454.

Connectograms they have been used to illustrate the damage suffered by Phineas Gage in his traumatic brain injury.

the connectogram

The connectogram shows regions of the brain, their physical properties and connectivity.

The image is divided into two halves — the left and right hemisphere. Within each half, regions are grouped into lobes (frontal, temporal, occipital, etc.) from anterior (top of image) to posterior (bottom of image). Within each lobe, fine anatomical and functional divisions (parcelations) are shown as labeled colored segments. The label of each segment is an abbreviated code. For example, SupPrCS is the superior part of the precentral sulcus.

The order and position of the parcelations is fixed across patients and composes a static coordinate system.

For each patient, measures of the parcelations are shown as a series of heat maps. These measures depend on the specific data set and can include grey matter volume, surface area, cortical thickness, curvature and degree connectivity (e.g. Fig 4 in Irimia et al, 2012).

Within the center of the connectogram are the observed connections between parcelations, measured in vivo (Human Connectome Project (HCP)).

data input

This tutorial includes a script, parsemap (see tutorials/8/19 directory), which generates the data files to create a connectogram. This script requires the list of parcelations and, optionally, a list of connections between them.

list of parcelations

This file defines the parcelation region lobe and name, color, (r g b), and measures, z1...z5. You'll find an example in map.txt. For this example, the measures data is random and the measures do not correspond to any specific property. The lobe, parcelation codes and colors are taken from Irimia et al, 2012.

# lobe parcelation r g b z1 z2 z3 z4 z5
Fro TrFPoG/S 255 153 153 0.910094 0.265257 0.893188 0.220351 0.810623
Fro FMarG/S 204 0 51 0.631798 0.571077 0.332158 0.104455 0.173531
Fro MFS 255 153 51 0.502931 0.567394 0.854165 0.0401409 0.484983
Ins ALSHorp 0 255 204 0.426026 0.325782 0.104662 0.428916 0.101814
Ins ACirInS 102 255 255 0.623148 0.6187 0.779997 0.488031 0.482945
Ins ALSVerp 0 255 255 0.98955 0.925851 0.642174 0.747365 0.254355
Lim ACgG/S 255 255 180 0.399686 0.345312 0.201031 0.322008 0.377663
Lim MACgG/S 255 240 191 0.336171 0.570686 0.437 0.87439 0.899756
Lim SbCaG 255 153 200 0.643938 0.517941 0.894874 0.839202 0.77888

The parsemap script uses the order of the parcelations in the file to determine their order in the image.

This example uses 5 measures for each parcelation, but the parsemap script will work if you don't have any measures and are only drawing links between regions.

# lobe parcelation r g b
Fro TrFPoG/S 255 153 153
Fro FMarG/S 204 0 51
Fro MFS 255 153 51

In this case, you'll need to adjust etc/circos.conf and remove mention of the heatmaps.

list of connections

The second file is the list of connections (see map.links.txt), which looks like

# hemisphere parcelation hemisphere parcelation connection_type connection_score
r InfFGOrp l PosCS 1 0.0229917613607071
l BSt l SbOrS 1 0.213414893099078
l TPl r Pu 0 0.26688626172767

The connection type and score do not corespond to any specifc property. I have included them here to show you how to use rules in the Circos configuration file to change the way the connection links are drawn.

Replace these two files with your data.

You can move the parsemap script to another location on your filesystem (e.g. /usr/local/bin) if you plan on using it for other images.

> cd /path/to/image
> /usr/local/bin/parsemap -map map.txt -links map.links.txt

Circos data files

The parsemap script generates the data files that are required to create the image.

To create the data files, run the parsemap script (Windows users should read this tutorial first)

# create the configuration and data files
> ./parsemap -map map.txt -links map.links.txt -debug
debug[1] wrote file etc/color.brain.conf
debug[1] wrote file data/segments.txt
debug[1] wrote file etc/segment.order.conf
debug[1] wrote file data/structure.label.txt
debug[1] wrote file data/measure.0.txt
debug[1] wrote file data/measure.1.txt
debug[1] wrote file data/measure.2.txt
debug[1] wrote file data/measure.3.txt
debug[1] wrote file data/measure.4.txt
debug[1] wrote file data/links.txt

You'll need to supply the remaining configuration files that define how the image is organized — sample configuration can be found in etc/. These are etc/circos.conf, etc/ideogram*conf, etc/ticks*conf and etc/bands.conf.

parcelation color

The RGB colors for each parcelation were taken from Appendix 1 in Irimia et al, 2012.

# etc/color.brain.conf
trfpogs = 255,153,153
fmargs = 204,0,51
mfs = 255,153,51
lors = 102,0,0
sbors = 255,51,102
ors = 255,204,204
rg = 255,204,153

The colors are named after the parcelations, in lowercase form and without any non-word characters (e.g. IntPS/TrPS becomes intpstrps).

lobe/parcelation axis

The lobe and segment definitions are stored in the data/segments.txt file.

Here, you'll have to remember that Circos was originally designed to display data in genomics, where the axes are typically chromosomes. The segments (lobes) take place of chromosomes and parcelations take place of cytogenetic bands, which are visual features on chromosomes.

Each lobe gets a separate entry for the left and right hemisphere. Its size is determined by the number of parcelations, arbitrary sized at 100.

# left frontal lobe (fro-l)
chr - fro-l Fro 0 2099 black
# right frontal lobe (fro-r)
chr - fro-r Fro 0 2099 black
# left insula (ins-l)
chr - ins-l Ins 0 799 black
# right insula (ins-r)
chr - ins-r Ins 0 799 black

The fro-l field is the name of the Circos axis that corresponds to the lobe and Fro is its label. The last field is the color of the lobe, but we will not be using this because the lobe will be covered with colored parcelations.

Parcelations are registered as bands within each lobe. Each line defines the parcelation as belonging to a specific Circos axis (e.g. lobe, fro-l) with a start/end position (e.g. 0, 99). The final field is the color of the parcelation, which was previously defined in etc/color.brain.conf. The 3rd and 4th fields in a band definition are currently not being used by Circos (they exist for legacy reasons).

band fro-l TrFPoG/S TrFPoG/S 0 99 trfpogs
band fro-l FMarG/S FMarG/S 100 199 fmargs
band ins-l ALSHorp ALSHorp 0 99 alshorp
band ins-l ACirInS ACirInS 100 199 acirins
band ins-l ALSVerp ALSVerp 200 299 alsverp
band lim-l ACgG/S ACgG/S 0 99 acggs
band lim-l MACgG/S MACgG/S 100 199 macggs
band lim-l SbCaG SbCaG 200 299 sbcag

It's important to note that the parcelations, defined as bands, are not directly referenced when plotting data. They are properties of the axis — they are not used to identify positions. See the section on parcelation labels and measures below for an explanation.

lobe order

Once the lobes are defined, their order in the figure is determined by the chromosomes_order field. Again, the genomic origins of Circos show through.

chromosomes_order = fro-r,ins-r,lim-r,tem-r,par-r,occ-r,sbc-r,ceb-r,bst,ceb-l,sbc-l,occ-l,par-l,tem-l,lim-l,ins-l,fro-l

By design, the brain stem lobe (bst) does not have a left and right version.

parcelation labels

Text labeling each parcelation is drawn as a text track. The input data for this is data/structure.label.txt,

fro-l 0 99 TrFPoG/S
fro-l 100 199 FMarG/S
fro-l 200 299 MFS
ins-l 0 99 ALSHorp
ins-l 100 199 ACirInS
ins-l 200 299 ALSVerp
lim-l 0 99 ACgG/S
lim-l 100 199 MACgG/S
lim-l 200 299 SbCaG

The text track stores the name of the parcelation region independently of the parcelation definitions, which was stored as bands entries. Circos currently does not support showing the names of the bands directly — you need to create a separate file with these labels and draw the labels using a data track.

Notice that the positions of the labels is determined relative to the lobe, not the parcelation region (e.g. MFS is at position 200-299 on fro-l). This is a result of the fact that the lobe forms the coordinate axis, not the parcelation region. The region is just a visual feature on the axis and cannot be addressed directly.

If you're very keen, you might be asking: why not make each parcelation region into its own axis? Yes, this is possible, but if the figure was organized this way there would be no way of organizing the regions into higher-level structures (e.g. lobes). By making each axis a lobe, and dividing it into regions, we can later write rules that check whether a data point lies on a specific lobe.

parcelation measures heat maps

The measures for each parcelation are defined in data/measure.*.txt

fro-l 0 99 0.910094
fro-l 100 199 0.631798
fro-l 200 299 0.502931
ins-l 0 99 0.426026
ins-l 100 199 0.623148
ins-l 200 299 0.989550
lim-l 0 99 0.399686
lim-l 100 199 0.336171
lim-l 200 299 0.643938


Links are stored as connected pair of axis and coordinates.

fro-r 700 799 par-l 300 399 type=1,score=0.022992
bst 0 99 fro-l 400 499 type=1,score=0.213415
tem-l 700 799 sbc-r 0 99 type=0,score=0.266886

The type and score parameters annotate each link and can be referenced in rules to change the format of the link.

Circos configuration files

The main configuration file is etc/circos.conf. This file contains all of the parameters that define the position and content of elements in the image, such as axis position and data tracks. Using <<include ...>> directives in this file, content from other files can be imported.

ideogram layout

The axis segments (here, brain lobes) are called ideograms in Circos. This vocabular is derived from the term given to a graphical representation of a chromosome.

The position, thickness and spacing of lobe ideograms is defined in etc/ideogram.conf, which is imported using the <<include ideogram.conf>> directive.

# circos.conf
<<include ideogram.conf>>

The etc/ideogram.conf file is

# ideogram.conf

# spacing between lobes is 0.5% of figure circumference
default = 0.005r
<pairwise fro-l fro-r>
# spacing between left and right frontal lobe ideogram (top center of image) is
# 5x default - this provides room for legend
spacing = 5r

# lobe thickness and position, included from file
<<include ideogram.position.conf>>

# lobe label size and format, included from file
<<include ideogram.label.conf>>

# parcelation colors, included from file
<<include bands>>


The position and thickness of the lobe segments is imported from the etc/ideogram.position.conf file. Storing parameters in multiple files makes the configuration more modular and allows you to reuse components of one figure in another.

# ideogram.position.conf

# position of the lobe axis segments, relative to radius of image
radius           = 0.85r

# thickness of lobe axis segments, in pixels
thickness        = 75p

# the color of each segment is "black" as defined in segments.txt - here we
# don't want this color applied, so fill=no
fill             = no

# the segments have a 1 pixel outline
stroke_thickness = 1
stroke_color     = black

The position and format of labels for each lobe segment are specified in etc/ideogram.label.conf.

# ideogram.label.conf

show_label       = yes
# for a list of fonts, see etc/fonts.conf in Circos distribution
label_font       = default

# set the label position to be at edge of inscribed circle, less 30 pixels
label_radius     = dims(image,radius)-30p
label_size       = 24

# labels can be parallel to axis segments, or perpendicular 
label_parallel   = yes

# force upper case for labels
label_case       = upper

Recall that the parcelation regions were defined as bands in the data/segments.txt file. Here I toggle the display of the bands.

# bands.conf

show_bands            = yes

# fill the bands with the color defined in segments.txt
fill_bands            = yes

# give the band an outline
band_stroke_thickness = 1
band_stroke_color     = black

# 0 - fully opaque
# 1 - least transparent
# 5 - most transparent
band_transparency     = 0

The axis progression of left hemisphere lobes is reversed, using a regular expression that selects all lobes whose names contain -l.

chromosomes_reverse = /.*-l/


The image contains a tick in the center of each paracelation region, together with a grid line that extends inward to the start of links. This is achieved with parameters defined in etc/ticks.conf.

First, recall that each parcelation region was made to be 100 units in size (in data/segments.txt). This multiplier is arbitrary, but necessary because Circos works only with integer coordinates. Without the multiplier, it would not be possible to specify a position in the middle of the region.

We also define the chromosomes_units to be 100

chromosomes_units = 100
<<include ticks.conf>>

so that we can use this value as a short cut when defining ticks.

Two groups of ticks are defined, spaced every 1u (100) and every 0.5u (50).

# ticks.conf

show_ticks          = yes
show_tick_labels    = yes
show_grid           = yes


radius           = dims(ideogram,radius_outer)
color            = black
thickness        = 2p
size             = 0

# ticks for middle of parcelation region
spacing        = 0.5u
# length of tick, overwrites the default 0 value
size           = 5p
# will have a grid
grid           = yes
grid_color     = black
grid_thickness = 1p
# from inner edge of lobe axis segment to 0.825r
grid_start     = 1r-conf(ideogram,thickness)
grid_end       = 0.825r

# 0.5u ticks defined above will also be shown at parcelation
# boundaries because they are shown every 50 (50, 100, 150, 200,
# ...). The 1u ticks (100, 200, ...) take precedence (because of
# larger spacing) and act to suppress the 0.5u ticks (1u tick have
# default size 0 and no grid).
spacing        = 1u


parcelation labels

The parcelation labels are displayed as a text track.

type       = text
file       = data/structure.label.txt
color      = black
label_font = default
label_size = 20
r0         = 1r
r1         = 1.5r
rpadding   = 10p

parcelation heat maps

Each parcelation has five properties, each displayed as a heat map. The heat maps are similarly formatted and are therefore patterened after a template. While it's not required that you use a template in this case, it makes rearranging track positions easier and the configuration file tidier.

A track template differs from a typical track only in that its parameter values depend on a dynamic variable. Typically, this variable is a counter—a variables whose values change in each <plot> block.

The heatmap template looks like this

# heatmap.conf
type         = heatmap
# use the value of the counter, via counter(heatmap), to determine the file
# for this block
# 1st block: data/measure.0.txt
# 2nd block: data/measure.1.txt
# ...
file         = data/measure.counter(heatmap).txt
# use the value of the counter to select the color for the heat map
# from the hm_colors configuration parameter
color        = eval((split(",","conf(hm_colors)"))[counter(heatmap)])
# the counter value is used to derive the radial position of the track, from
# hm_r (initial radial position), hm_w (track width) and hm_pad (track padding)
# parameters
r1           = eval(sprintf("%fr",conf(hm_r)-counter(heatmap)*(conf(hm_w)+conf(hm_pad))))
r0           = eval(sprintf("%fr",conf(hm_r)-counter(heatmap)*(conf(hm_w)+conf(hm_pad))+conf(hm_w)))
stroke_color = white
stroke_thickness = 3

and is used in etc/circos.conf like this

# define parameters used in the heatmap template
hm_r      = 0.96  # radial position of first heat map
hm_w      = 0.025 # heat map width
hm_pad    = 0.005 # heat map padding

# heat map track colors
#           1st track  2nd track     3rd track    4th track   5th track
#hm_colors = greys-4-seq,greys-4-seq,greys-4-seq,greys-4-seq,greys-4-seq
hm_colors = reds-4-seq,oranges-4-seq,greens-4-seq,blues-4-seq,purples-4-seq


<<include heatmap.conf>>
<<include heatmap.conf>>
<<include heatmap.conf>>
<<include heatmap.conf>>
<<include heatmap.conf>>

connectogram links

Links are defined in a <link> block.

file   = data/links.txt
radius = 0.825r 

bezier_radius = 0r
bezier_radius_purity = 0.5
crest         = 0.25
thickness     = 2
color         = black

The radius parameter defines the radial position of the link ends, while the bezier_radius defines the radial position of the control point used to draw the curve.

The ancillary parameters, crest and bezier_radius_purity, affect the angle at which the links terminate and the control point radius for short links, respectively.

link rules

Recall that the link input data included two parameters, type and score. We can use <rule> blocks to change how the links are formatted based on these parameters.

Parameter values are referenced using var() and format values can be expressed as Perl code when passed through eval().


# this rule will apply to all links, since the condition is always true
condition = 1
# map the score [0,1] onto thickness [1,5]
thickness = eval(remap_int(var(score),0,1,1,5))
# force continued testing of rules - otherwise a rule that
# passes a condition short-circuits further testing
flow      = continue

# select links with type=0
condition = var(type) == 0
# map the score [0,1] onto the colors greys-5-seq-1..greys-5-seq-5 
color     = eval(sprintf("greys-5-seq-%d",remap_int(var(score),0,1,1,5)))

# select links with type=1
condition = var(type) == 1
# same as above, except use the reds Brewer palette
color     = eval(sprintf("reds-5-seq-%d",remap_int(var(score),0,1,1,5)))



I've generated a couple of layout variants for the connectogram (see images) to give you an idea of other layouts.

outward links for intra-lobe connections

Link geometry can be changed with rules.

# all links terminate further inward
radius = 0.7r
# links between the same lobes have the control point placed
# further from the center than their ends (1r vs 0.7r), making
# them curve outward
condition = var(chr1) eq var(chr2)
bezier_radius = 1r
# slight separation between ends of outward and inward links (0.71r vs 0.7r)
radius    = 0.71r
# continue with other rules for these links
flow      = continue

focus on parcelation

The second variant (see etc.2/ directory in this tutorial) has adjusted geometry to make the parcelation segments more central in the image. To do this, the ideogram radius is reduced

# ideogram.position.conf
radius = 0.65r

Inter-lobe links point inward and terminate at the inner radius of the parcelation regions. Intra-lobe links point outward, and terminate at the outer radius.

condition = var(chr1) eq var(chr2)
bezier_radius = 1.25r
radius    = dims(ideogram,radius_outer)
flow      = continue

The heatmaps, being an annotation of the parcelation regions, are moved further out together with labels.

# circos.conf
hm_r      = 1.3

The tick grid that connects the parcelation labels with segments is made lighter, to avoid interference with outward links.

# ticks.conf


grid_color     = black_a3