Getting started with Circos

Once you’ve installed Circos, you can get started with Circos by following the Circos quick guide. Bascially this post was done just by following the guide, which is obviously what you should be looking at; this page just acts as a reminder for myself of what I’ve done.

According to the Hello World guide, the bare minimum that is required in the configuration file is this:

# circos.conf

karyotype = /home/davetang/src/circos-0.62-1/data/karyotype/karyotype.human.txt

<ideogram>

<spacing>
default = 0.005r
</spacing>

radius    = 0.9r
thickness = 20p
fill      = yes

</ideogram>

################################################################
# The remaining content is standard and required. It is imported
# from default files in the Circos distribution.
#
# These should be present in every Circos configuration file and
# overridden as required. To see the content of these files,
# look in etc/ in the Circos distribution.

<image>
# Included from Circos distribution.
<<include /home/davetang/src/circos-0.62-1/etc/image.conf>>
</image>

# RGB/HSV color definitions, color lists, location of fonts, fill patterns.
# Included from Circos distribution.
<<include /home/davetang/src/circos-0.62-1/etc/colors_fonts_patterns.conf>>

# Debugging, I/O an dother system parameters
# Included from Circos distribution.
<<include /home/davetang/src/circos-0.62-1/etc/housekeeping.conf>>

Now if I run Circos:

/home/davetang/src/circos-0.62-1/bin/circos -conf test.conf
debuggroup conf 0.34s welcome to circos v0.62-1 25 Jun 2012
debuggroup conf 0.34s loading configuration from file test.conf
debuggroup conf 0.34s looking for conf file test.conf
debuggroup conf 0.34s found conf file test.conf
debuggroup summary 0.54s debug will appear for these features: summary
debuggroup summary 0.54s parsing karyotype and organizing ideograms
debuggroup summary 0.74s applying global and local scaling
debuggroup summary 0.75s allocating image, colors and brushes
debuggroup summary 1.66s drawing highlights and ideograms
debuggroup summary,output 1.77s generating output
debuggroup summary,output 2.48s created PNG image ./circos.png (50 kb)
debuggroup summary,output 2.48s created SVG image ./circos.svg (5 kb)

I get this figure:

Now to add ticks and labels.

First adding labels:

# circos.conf

karyotype = /home/davetang/src/circos-0.62-1/data/karyotype/karyotype.human.txt

<ideogram>

<spacing>
default = 0.005r
</spacing>

# Ideogram position, fill and outline

radius           = 0.90r
thickness        = 20p
fill             = yes
stroke_color     = dgrey
stroke_thickness = 2p

# Minimum definition for ideogram labels.

show_label       = yes
# see etc/fonts.conf for list of font names
label_font       = default
label_radius     = 1r + 75p
label_size       = 30
label_parallel   = yes

</ideogram>

################################################################
# The remaining content is standard and required. It is imported
# from default files in the Circos distribution.
#
# These should be present in every Circos configuration file and
# overridden as required. To see the content of these files,
# look in etc/ in the Circos distribution.

<image>
# Included from Circos distribution.
<<include /home/davetang/src/circos-0.62-1/etc/image.conf>>
</image>

# RGB/HSV color definitions, color lists, location of fonts, fill patterns.
# Included from Circos distribution.
<<include /home/davetang/src/circos-0.62-1/etc/colors_fonts_patterns.conf>>

# Debugging, I/O an dother system parameters
# Included from Circos distribution.
<<include /home/davetang/src/circos-0.62-1/etc/housekeeping.conf>>

Running Circos on this updated configuration file you get:

Now to add ticks. It is recommended that the ticks configuration file is kept separately e.g. ticks.conf. And actually the ideogram section can also be kept separately, as long as you “include” these config files in the main configuration file e.g. test3.conf. Below are the three separate files:

test3.conf:

karyotype = /home/davetang/src/circos-0.62-1/data/karyotype/karyotype.human.txt
chromosomes_units = 1000000
<<include ideogram.conf>>
<<include ticks.conf>>
<image>
<<include /home/davetang/src/circos-0.62-1/etc/image.conf>>
</image>
<<include /home/davetang/src/circos-0.62-1/etc/colors_fonts_patterns.conf>>
<<include /home/davetang/src/circos-0.62-1/etc/housekeeping.conf>>

ideogram.conf:

<ideogram>

<spacing>
default = 0.005r
</spacing>

# Ideogram position, fill and outline
radius           = 0.90r
thickness        = 20p
fill             = yes
stroke_color     = dgrey
stroke_thickness = 2p

# Minimum definition for ideogram labels.

show_label       = yes
# see etc/fonts.conf for list of font names
label_font       = default
label_radius     = dims(image,radius) - 60p
label_size       = 30
label_parallel   = yes

</ideogram>

ticks.conf:

show_ticks          = yes
show_tick_labels    = yes

<ticks>
radius           = 1r
color            = black
thickness        = 2p

# the tick label is derived by multiplying the tick position
# by 'multiplier' and casting it in 'format':
#
# sprintf(format,position*multiplier)
#

multiplier       = 1e-6

# %d   - integer
# %f   - float
# %.1f - float with one decimal
# %.2f - float with two decimals
#
# for other formats, see http://perldoc.perl.org/functions/sprintf.html

format           = %d

<tick>
spacing        = 5u
size           = 10p
</tick>

<tick>
spacing        = 25u
size           = 15p
show_label     = yes
label_size     = 20p
label_offset   = 10p
format         = %d
</tick>

</ticks>

Running:

circos -conf test3.conf

You get:

Now to manipulate the ideograms, by selecting only a subset to output at different scales and colours.

test4.conf:

karyotype = data/karyotype/karyotype.human.txt
chromosomes_units = 1000000

chromosomes_display_default = no
chromosomes                 = /hs[1-4]$/

chromosomes_scale   = hs1=0.5r,/hs[234]/=0.5rn

chromosomes_reverse = /hs[234]/

chromosomes_color   = hs1=red,hs2=orange,hs3=green,hs4=blue

<<include ideogram.conf>>

<<include ticks.conf>>

<image>
<<include etc/image.conf>>
</image>

<<include etc/colors_fonts_patterns.conf>>

<<include etc/housekeeping.conf>>

Using the same ideogram.conf and ticks.conf files and running:

circos -conf test4.conf

You get:

Now to add links, which are associations between two genomic positions. From the tutorial:

Links can be visually formatted using rules, which compose of a decision tree of expressions that are evaluated for every link. Rules test links based on data value, and can therefore dynamically change how a link appears based on its position, size, or other parameter.

The tutorial uses the “segdup.txt” file, which can be downloaded at http://circos.ca/software/download/tutorials/. However, the file is quite huge and I just want to see a few links. The format of the segdup.txt file is as such:

hs1 98454 130259 hs7 34001 66051

So I’ll just make up some links:

hs1 10000 50000 hs2 10000 50000
hs2 10000 50000 hs3 10000 50000
hs3 100000 200000 hs4 1000000 1100000

and saved it inside a text file called my_link.txt.

Now the test5.conf file:

karyotype = data/karyotype/karyotype.human.txt
chromosomes_units = 1000000
chromosomes_display_default = no
chromosomes                 = /hs[1-4]$/
chromosomes_reverse         = /hs[234]/
chromosomes_scale           = hs1=0.5r,/hs[234]/=0.5rn
<colors>
chr1* = red
chr2* = orange
chr3* = green
chr4* = blue
</colors>
<links>
   <link>
      file          = my_link.txt
      radius        = 0.8r
      bezier_radius = 0r
      color         = black_a4
      thickness     = 2
      <rules>
         <rule>
            condition     = var(intrachr)
            show          = no
         </rule>
         <rule>

            condition     = 1
            color         = eval(var(chr2))
            flow          = continue
         </rule>
         <rule>
            condition     = from(hs1)
            radius1       = 0.99r
         </rule>
         <rule>
            condition     = to(hs1)
            radius2       = 0.99r
         </rule>
      </rules>
   </link>
</links>
<<include ideogram.conf>>
<<include ticks.conf>>
<image>
<<include etc/image.conf>>
</image>
<<include etc/colors_fonts_patterns.conf>>
<<include etc/housekeeping.conf>>

Using the same ideogram.conf and ticks.conf files and running:

circos -conf test5.conf

You now get:

In addition to relationships/links, Circos can produce line plots, scatter plots, histograms and heat maps.

The line plot, scatter plot, heat map and histogram share the same data format, which is:

#chr start end value [options]
hs3 196000000 197999999 71.0000

For the example the sample file is data/5/segdup.hs1234.hist.txt, which looks like this:

hs1 0 1999999 180.0000
hs1 2000000 3999999 34.0000

Building on my minimalistic example above, let’s make some histograms:

hs1 100 50000 100
hs2 100 50000 200
hs3 100 50000 300
hs3 1000 200000 400
hs4 10000 1100000 500

And save it in a file called my_link_hist.txt. Here’s the test6.conf file:

karyotype = data/karyotype/karyotype.human.txt
chromosomes_units = 1000000

chromosomes_display_default = no
chromosomes                 = /hs[1234]$/

<colors>
chr1* = red
chr2* = orange
chr3* = green
chr4* = blue
</colors>

chromosomes_reverse = /hs[234]/
chromosomes_scale   = hs1=0.5r,/hs[234]/=0.5rn

<plots>
   <plot>
      type = histogram
      file = my_link_hist.txt
      r1   = 0.88r
      r0   = 0.81r
      fill_color = vdgrey
      extend_bin = no
#<rules>
#<<include exclude.hs1.rule>>
#</rules>
   </plot>
</plots>

<links>
   <link>
      file          = my_link.txt
      radius        = 0.8r
      bezier_radius = 0r
      color         = black_a4
      thickness     = 2
      <rules>
         <rule>
            condition     = var(intrachr)
            show          = no
         </rule>
         <rule>
            condition     = 1
            color         = eval(var(chr2))
            flow          = continue
         </rule>
         <rule>
            condition     = from(hs1)
            radius1       = 0.99r
         </rule>
         <rule>
            condition     = to(hs1)
            radius2       = 0.99r
         </rule>
      </rules>
   </link>
</links>
<<include ideogram.conf>>
<<include ticks.conf>>
<image>
<<include etc/image.conf>>                
</image>
<<include etc/colors_fonts_patterns.conf>>
<<include etc/housekeeping.conf>>

And again using the same ideogram.conf and ticks.conf, run the following command:

circos -conf test6.conf

Which gives you:

Now to add some axes and track backgrounds. These configurations can be stored in another file, e.g. axes.conf and backgrounds.conf and here they are:

axes.conf:

<axes>
   show = data
   thickness = 1
   color     = lgrey
   <axis>
      spacing   = 0.1r
   </axis>
   <axis>
      spacing   = 0.2r
      color     = grey
   </axis>
   <axis>
      position  = 0.5r
      color     = red
   </axis>
   <axis>
      position  = 0.85r
      color     = green
      thickness = 2
   </axis>
</axes>

backgrounds.conf:

<backgrounds>
   show  = data
   <background>
      color = vvlgrey
   </background>
   <background>
      color = vlgrey
      y0    = 0.2r
      y1    = 0.5r
   </background>
   <background>
      color = lgrey
      y0    = 0.5r
      y1    = 0.8r
   </background>
   <background>
      color = grey
      y0    = 0.8r
   </background>
</backgrounds>

Now place the “include axes.conf” and “include backgrounds.conf” lines inside the “plot” block:

test7.conf

karyotype = data/karyotype/karyotype.human.txt
chromosomes_units = 1000000

chromosomes_display_default = no
chromosomes                 = /hs[1234]$/

<colors>
chr1* = red
chr2* = orange
chr3* = green
chr4* = blue
</colors>

chromosomes_reverse = /hs[234]/
chromosomes_scale   = hs1=0.5r,/hs[234]/=0.5rn

<plots>
   <plot>
      type = histogram
      file = my_link_hist.txt
      r1   = 0.88r
      r0   = 0.81r
      fill_color = vdgrey
      extend_bin = no

      <<include axes.conf>>
      <<include backgrounds.conf>>

   </plot>
</plots>

<links>
   <link>
      file          = my_link.txt
      radius        = 0.8r
      bezier_radius = 0r
      color         = black_a4
      thickness     = 2
      <rules>
         <rule>
            condition     = var(intrachr)
            show          = no
         </rule>
         <rule>
            condition     = 1
            color         = eval(var(chr2))
            flow          = continue
         </rule>
         <rule>
            condition     = from(hs1)
            radius1       = 0.99r
         </rule>
         <rule>
            condition     = to(hs1)
            radius2       = 0.99r
         </rule>
      </rules>
   </link>
</links>
<<include ideogram.conf>>
<<include ticks.conf>>
<image>
<<include etc/image.conf>>                
</image>
<<include etc/image.conf>>                
</image>
<<include etc/colors_fonts_patterns.conf>> 
<<include etc/housekeeping.conf>>

And run Circos and you get this figure:

Next heatmaps! Heatmaps use the same data format as histograms. For example, the segdup.hs1234.heatmap.txt file looks like this:

hs1 0 1999999 113.0000 id=hs1
hs1 0 1999999 40.0000 id=hs4
hs1 0 1999999 20.0000 id=hs2
hs1 0 1999999 7.0000 id=hs3

To simplify things, the next figure will just contain the heatmap.

test8.conf

karyotype = data/karyotype/karyotype.human.txt
chromosomes_units = 1000000
chromosomes_display_default = no
chromosomes                 = /hs[1234]$/
<colors>
chr1* = red
chr2* = orange
chr3* = green
chr4* = blue
</colors>
chromosomes_reverse = /hs[234]/
chromosomes_scale   = hs1=0.5r,/hs[234]/=0.5rn

<plots>

<plot>
type  = heatmap
file  = segdup.hs1234.heatmap.txt
r1    = 0.89r
r0    = 0.88r

color = hs1_a5,hs1_a4,hs1_a3,hs1_a2,hs1_a1,hs1

scale_log_base = 5

<rules>
   <rule>
      condition = var(id) ne "hs1"
      show      = no
   </rule>
</rules>

</plot>

</plots>

<<include ideogram.conf>>

<<include ticks.conf>>

<image>
<<include etc/image.conf>>                
</image>

<<include etc/colors_fonts_patterns.conf>> 

<<include etc/housekeeping.conf>>

And using all the same conf files as above, the output figure is:

And finally the last tutorial of the quick guide is adding text.

The gene labels file (data/6/genes.labels.txt) looks like this:

hs1 100425066 100487997 DBT
hs1 10381671 10402787 PGD

For fun let’s make something like:

hs1 10000 1000000 Dave
hs2 10000 1000000 Tang
hs3 10000 1000000 Dot
hs4 10000 1000000 Org

test9.conf

karyotype = data/karyotype/karyotype.human.txt
chromosomes_units = 1000000

chromosomes_display_default = no
chromosomes                 = /hs[1234]$/

<colors>
chr1* = red
chr2* = orange
chr3* = green
chr4* = blue
</colors>

chromosomes_reverse = /hs[234]/
chromosomes_scale   = hs1=0.5r,/hs[234]/=0.5rn

<plots>

   <plot>
      type  = text
      file  = label.txt
      r1    = 0.8r
      r0    = 0.6r
      label_font = light
      label_size = 52p
      rpadding   = 5p
      show_links     = no
      link_dims      = 0p,2p,5p,2p,2p
      link_thickness = 2p
      link_color     = black

      <rules>
         <rule>
            condition  = var(value) =~ /a/i
            label_font = bold
            flow       = continue
         </rule>
         <rule>
            condition  = var(value) =~ /b/i
            color      = blue
         </rule>
      </rules>
   </plot>
</plots>

<<include ideogram.conf>>

<<include ticks.conf>>

<image>
<<include etc/image.conf>>                
</image>

<<include etc/colors_fonts_patterns.conf>> 

<<include etc/housekeeping.conf>>

Again, everything else the same as before and voila we get:

There’s so much more to learn but for now that was getting started with Circos.

Print Friendly, PDF & Email



Creative Commons License
This work is licensed under a Creative Commons
Attribution 4.0 International License
.
5 comments Add yours
  1. Hi Davetang,
    I tried installing circos from the instructions mentioned in your blog. However, when I tried to run it using the test.conf file you provided, it gave me the following error.
    Can you please help in enlightning me of everything is OK ?

    regards,
    Amit.

    root@iobl-amit2:/local/home/amit/Downloads/circos-0.64/bin# ./circos -conf test.conf
    debuggroup summary 0.05s welcome to circos v0.64 2 May 2013
    debuggroup summary 0.05s loading configuration from file test.conf
    debuggroup summary 0.05s found conf file test.conf

    *** CIRCOS ERROR ***

    CONFIGURATION FILE ERROR

    Your parameter [cat test.conf | grep -v “^] contains a white space. This is
    not allowed. You either forgot a ‘=’ in assignment (e.g. ‘red 255,0,0’ vs ‘red
    = 255,0,0’) or used a multi-word parameter name

    (e.g. ‘my red = 255,0,0’ vs ‘my_red = 255,0,0’

    If you are having trouble debugging this error, use this tutorial to learn how
    to use the debugging facility

    http://www.circos.ca/tutorials/lessons/configuration/debugging

    If you’re still stumped, get support in the Circos Google Group

    http://groups.google.com/group/circos-data-visualization

    Stack trace:
    at /local/home/amit/Downloads/circos-0.64/bin/../lib/Circos/Error.pm line 354
    Circos::Error::fatal_error(‘configuration’, ‘multi_word_key’, ‘cat test.conf | grep -v “^’) called at /local/home/amit/Downloads/circos-0.64/bin/../lib/Circos/Configuration.pm line 534
    Circos::Configuration::repopulateconfiguration(‘HASH(0x359e560)’) called at /local/home/amit/Downloads/circos-0.64/bin/../lib/Circos/Configuration.pm line 248
    Circos::Configuration::populateconfiguration(‘configfile’, ‘test.conf’) called at /local/home/amit/Downloads/circos-0.64/bin/../lib/Circos.pm line 202
    Circos::run(‘Circos’, ‘configfile’, ‘test.conf’) called at ./circos line 301

    1. There’s something wrong with your test.conf file as the error says:

      Your parameter [cat test.conf | grep -v “^] contains a white space. This is
      not allowed. You either forgot a ‘=’ in assignment (e.g. ‘red 255,0,0’ vs ‘red
      = 255,0,0’) or used a multi-word parameter name

  2. Hey Dave. Thank you for the post. This is exactly what I have been looking for, and the tutorial has proven helpful. I wish this tutorial was on the Circos website.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.