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.
One of the core uses of Circos is to show the relationships between positions on axes. Axes might be chromosomes and might indicate translocations. Or the axes could be categories or entities (e.g. countries) and indicate some relationship between them, such as migration of people.
A lot of the syntax for defining parameters that control how links are defined carry over directly from the syntax for highlights.
All link data sets are defined within the <links> block. Typically this block contains global parameter settings in its root - these values become the default values for all link data.
Individual link data sets are defined within <link> blocks.
<links> # global parameters here <link> ... </link> <link> ... </link> </links>
Link data files are composed of position pairs defined on one line.
... hs1 100 200 hs2 250 300 hs1 400 550 hs3 500 750 hs1 600 800 hs4 150 350 ...
Links may also be defined across two lines. The lines are associated together using a link
id, which is unique for each pair. You must also have exactly two lines for each link
... segdup00010 hs1 100 200 segdup00010 hs2 250 300 segdup00011 hs1 400 550 segdup00011 hs3 500 750 segdup00012 hs1 600 800 segdup00012 hs4 150 350 ...
The two-line format is deprecated and may not be supported in future versions.
As with highlights, you can add an optional field to specify link-specific options.
... hs1 100 200 hs2 250 300 color=blue hs1 400 550 hs3 500 750 color=red,thickness=5p hs1 600 800 hs4 150 350 color=black ...
In this example, I draw data from a file of coordinates defined by segmental duplications. Each coordinate pair defines two regions of the genome that are defined as segmental duplications (>1kb in length, >90% similarity).
<links> <link> file = data/5/segdup.txt color = black_a5 radius = 0.95r bezier_radius = 0.1r thickness = 1 </link> </links>
If you need to draw links on segments for which the karyotype is not available — when the segments are not chromosomes from a common species — you'll need to create your own karyotype file.
For example, if you had 3 contigs of size 1000, 1500 and 2500 bp, you might create this file
# karyotype.txt chr - contig1 1 0 1000 black chr - contig2 2 0 1500 blue chr - contig3 3 0 2500 red
karyotype = karyotype.txt
Your link file might look like this
contig1 10 20 contig2 500 520 contig3 50 80 contig3 750 760 ...
Here the first link defines connections between
contig2:500-520 and the second between
The basic parameters for links are
radius— this is the radial position of the termination of the link; for relative values, if
radius< 1 then it is defined in terms of the inner ideogram radius, otherwise it is defined in terms of the outer ideogram radius
bezier_radius— the radial position of the third control point (in addition to the two positions defined by the link coordinates) used to draw the Bezier curve; if this parameter is not defined then straight lines will be used
color— color of the link line
thickness— thickness of the link line (note that this is not stroke_thickness, since the line isn't technically stroked)
record_limit— if this is defined, the number of records read from the file is capped; coordinate records are sampled from the start of the file; useful for debugging
All track types have default values. For links, these are
ribbon = no color = black thickness = 1 radius = 0.40r bezier_radius = 0r crest = 0.5 bezier_radius_purity = 0.75
and loaded from
etc/tracks/link.conf in the Circos distribution. This file is set by the
track_defaults parameter, which is set normally in
etc/housekeeping.conf. You can override defaults by setting the parameter to
<link> ... crest = undef ... </link>
<<include etc/housekeeping.conf>> track_defaults* = undef
Note that the
* syntax is required because you are overriding a parameter which is already defined at the same level in the configuration file.
Links can be drawn as straight lines or as quadratic Bezier curves.
For the latter, the start
p1 and end
p3 control points are
defined by the coordinate positions (angularly) and the radius
parameter (radially). The middle control point
p2 is defined by the mid
point between the coordinates (angularly) and
The Bezier curve is drawn to have its tangent at
p1 defined by the line
p1-p2 and at
p3 defined by the line
the image associated with this tutorial).