Use Circos to create concise, explanatory, unique and print-ready visualizations of your data.

Current version is 0.52.

Try the online version.

Visit this group

Current version is 0.52.
This is a bug release. Issues with ideogram ordering and axis breaks have been addressed.
Current tools version is v0.13.
New is categoryviewer, used to visualize categorical data and a significantly updated tableviewer. Read about the theory and practise of visualizing tabular data.

Circos Online An online version of Circos is now available to visualize tabular data. Turn your tables into informative images!

3x3 table	4x4 table
6x6 table	8x8 table

Conde Nast Porfolio features an article on personalized genome sequencing. An image by Circos appears in a double-page spread. The art direction called for something primarily artistic and visually appealing, but also connected to the content of the article.

An image created by Circos appears on the cover of the Sept/Oct issue of American Scientist.

The image accompanies an article by Elaine Ostrander about dog genetics and illustrates the deep sequence similarity between the human and dog genomes. Read about the figure.

Circos is used to generate a visualization of the 2007 Democratic and Republican Debates. The image was created by Jonathan Corum and Farhana Hossain, who discuss how the image was conceptualized.

Circos is featured in the Science section of the New York Times (22 Jan 2007).

Circos - a data viewer with comparative genomics in mind

Visualizing quantitative information - featuring work of Tufte

A variety of Circos posters are available.

Tick mark definitions are confined to the <ticks> block, with only a handful of tick-related parameters being in the root of the configuration tree. Some parameters in the ticks block control the formatting of the grid. This is discussed in another section in this tutorial.

My preference is to keep tick configuration in a separate configuration file, typically ticks.conf, which is imported into the main configuration using the <<include>> directive.

# circos.conf
<<include ticks.conf>>
...

Therefore, the ticks.conf file will be of main interest to you when following this set of tutorials.

toggling tick display

Use show_ticks and show_tick_labels to control whether ticks and associated labels are drawn.

show_ticks       = yes
show_tick_labels = yes

Tick labels are drawn only if ticks are drawn. Here, ticks refers to the radial lines that show progression of distance along the ideogram. Tick labels are the accompanying text elements that mark the position of the tick.

If you have a large number of ticks (1000s) they can take a while to draw. This applies in particular if you have defined a minimum distance between ticks, which causes some ticks to be suppressed. Therefore, once you have your ticks designed and you find that their display is slowing you down while you are designing the rest of the image, suppress the ticks temporarily with -no-show_ticks on the command line.

> bin/circos -no-show_ticks ...

Similarly, you can supress labels with -no-show-tick-labels.

tick block

The <ticks> block contains global tick parameters and individual <tick> blocks that specify how ticks at a given spacing (absolute or relative) or at a specific position (or positions) should be formatted.

<ticks>

  ... global tick parameters ...

  <tick>
  ... tick level parameters ...
  <tick>

  <tick>
  ... tick level parameters ...
  <tick>

  ...

<ticks>

global tick parameters

Global parameters influence every tick. They can be overridden with different values in individual <tick> blocks. The three basic tick parameters are the tick radius, label multiplier and orientation.

The radius specifies the radial position of the tick marks, which you generally want to set to the outer ideogram radius (but this is only a suggestion!).

The label multiplier is the constant used to multiply the tick value to obtain the tick label. For example, if the multiplier is 1e-6, then the tick mark at position 10,000,000 will have a label of 10. The multiplier is applied to the raw tick value, regardless of the value of chromosomes_unit.

The orientation controls whether the ticks and labels face out (orientation=out) or in (orientation=in). For example, you are drawing ticks at the outer ideogram radius, then an "out" orientation is appropriate. For ticks drawn at the inside radius, an "in" orientation should be used to avoid overlapping ticks and labels with the ideogram.

radius               = dims(ideogram,radius_outer)
label_multiplier     = 1e-6
orientation          = out

Note that for the radius, you can specify the radius by using the parsable dims() keyword. This keyword takes two arguments, feature and feature parameter. In this case, I've asked that the ticks be drawn at the outer radius of the ideogram. If you would like to shift the ticks away from this position, you can add a pixels offset. For example,

radius               = dims(ideogram,radius_outer) + 25p

would draw the the ticks at 25 pixels from the outer ideogram radius. This feature is useful if you'd like to draw data between the ideogram and the tick labels.

As you'll see in other tutorials on ticks, you can specify multiple radius values for ticks. Doing so will create several rings of tick marks.

local tick parameters

The location of ticks is controled by spacing (distance between adjacent ticks is fixed) or by specific position. Spacing can be either absolute (e.g. tick every 1Mb) or relative (tick every 1% of ideogram length).

Typically, one defines several sets of ticks by using <tick> blocks. Each set defines the display of ticks at a given spacing. For example, one could have three sets of ticks spaced at 1Mb, 5Mb and 10Mb, respectively, and formatted so that the 1Mb ticks are small and without labels whereas the 5Mb and 10Mb be larger and with labels. The 10Mb ticks might use a bolder font, for example, to give them greater visual weight.

Absolute spacing of ticks can be defined in units of bases (b, the natural unit along the ideogram) or chromosome units (u, whose size is defined by the chromosomes_units parameter). In the definition below, if chromosomes_units=10_000_000 then the ticks are spaced at 10Mb, 5Mb and 1Mb (10u, 5u and 1u).

<ticks>

  radius               = dims(ideogram,radius_outer)
  multiplier           = 1e-6

  <tick>
  spacing = 10u
  ... parameters for ticks every 10u (=10Mb)...
  <tick>

  <tick>
  spacing = 5u
  ... parameters for ticks every 5u (=5Mb)...
  <tick>

  <tick>
  spacing = 1u
  ... parameters for ticks every 1u (=1Mb)...
  <tick>

<ticks>

Tick marks are drawn in descending order of spacing. Therefore, for this example, the 10u ticks are drawn first, then all 5u ticks (except those already drawn every 10u) are drawn down, and then finally the 1u ticks. Unless force_display is set for a tick set, ticks at smaller spacing are not drawn at a position that already has another tick. In other words, the formatting of a tick mark is defined by the block associated with the spacing value that defines the largest divisor of the tick value.

Tick marks for positions outside of the range of the ideogram are not drawn. This applies in particular to cases where a chromosome is represented by multiple ideograms with axis breaks - there will be no ticks inside the region of the axis break.

The basic tick parameters are as follows. Note that most of the values require that a unit be provided (p = pixel, r = relative, u = chromosome unit). Other parameters, such as those that control relative spacing, are covered in other tick tutorials.

• spacing - the distance between the ticks in this set and should be expressed in units of chromosomes_units (u) or bases (b).
• chromosomes - optional list of ideograms on which ticks are drawn or are suppressed
• size - the length of the tick line, in pixels (p) or relative (r) to thickness of ideogram
• thickness - the thickness of the tick line, in pixels (p) or relative (r) to the size of the tick
• color - the color of the tick line and its label
• show_label - toggles display of the tick's associated label and is functional only if show_tick_labels is set
• label_size - controls the size of the tick's label in pixels (p) or relative (r) to the size of the tick
• label_offset - additional padding between the label and end of the tick mark, in pixels (p) or relative (r) to the size of the tick
• format - a printf style format applied to the label of the tick (e.g. %d for integer, %.nf for n-decimal float).

Finally a quick note about relative units. You'll note that "size" is a parameter than can be expressed in relative units (e.g. 0.2r). This parameter, when thus expressed, is calculated relative to another quantity.

When tick size is expressed in relative terms, the comparator is the tickness of the ideogram. Therefore ticks with size=0.1r will have a length that is 1/10th of the ideogram thickness. Tick thickness, on the other hand, uses the tick size as the comparator. Thus, ticks with thickness=0.1r will have a width that is 1/10th the size of their length. Similarly, if tick label size is defined relatively, it will be scaled by tick size.

The purpose of relative values is to reduce the work required to alter the configuration file when the size of the output bitmap image changes. For example, if you define all tick size values in relative terms, to maintain ticks of the same proportion you only need to change the ideogram thickness when the image size changes.

toggling tick display by ideogram

You can selectively suppress ticks for individual ideograms, or a range on any ideogram. There are two parameters in the <ticks> block, as well as in <tick> blocks, that control this.

<ticks>
# ticks will be displayed on every ideogram by default
chromosomes_display_default = yes
# all ticks will be suppressed on ideogram hs1 and in region
# 0-50Mb on hs2 (range is expressed in units of chromosomes_unit),
# and in region 100Mb+ on hs3
chromosomes = -hs1;-hs2:0-50;-hs3:100-)
...
</ticks>

An example of this kind of tick mark suppression is shown in the first image in this tutorial. You can individually suppress individual ticks by adding a chromosomes parameter to the <tick> block. For example, to remove 10Mb tick marks from hs2

<ticks>
chromosomes_display_default = yes
chromosomes = -hs1;-hs2:0-100;-hs3:100-)

<tick>
spacing     = 10u
chromosomes = -hs2
...
</tick>

...
</ticks>

When defining regions in which tick marks are not shown (these are entries prefixed by - such as -hs1), the regions in the <ticks> block combine with regions in the <tick> blocks in the OR sense (as sets, the union is computed).

When chromosomes_display_default=yes, you do not need to define which ideograms ticks appear on because tick mark visibility is on by default and you only need to define where tick marks are not shown.

If chromosomes_display_default=no, then things get a little bit more complicated, because you now need to define where tick marks will be shown and these definitions can contain regions of exclusion.

To show ticks only on specific ideograms or regions,

<ticks>
# ticks will not be displayed on every ideogram by default
chromosomes_display_default = no
# ticks only on these ideograms and/or regions
chromosomes = hs1;hs2:0-100;hs3:100-)
...
</ticks>

You can combine regions where tick marks should be shown with regions of exclusion within individual <tick> blocks to specifically control where ticks are drawn.

<ticks>
# ticks will not be displayed on every ideogram by default
chromosomes_display_default = no
# ticks only on these ideograms and/or regions
chromosomes = hs1;hs2:0-100;hs3:100-)

<tick>
spacing     = 5u
chromosomes = hs4
</tick>

<tick>
spacing     = 10u
chromosomes = -hs2;hs5
</tick>

</ticks>