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.
This work is licensed under a Creative Commons
Attribution 4.0 International License.
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
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
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.
Thanks for beautifully explaining. It helped me a lot.
Thanks Dave,
Please my major issue is how to move from a raw NGS file to a circos plot. I have a problem generating my karyotype file. Do I need to map my reads to a reference? If yes, how do i extract the chromosome positions from the the reads for the plot?
I will appreciate every help.