1. Directory Structure and Configuration

7. Debugging

Lesson Images Configuration

If Circos is not behaving as you expect, the first thing to do is to run it with a -debug flag. For example,

> bin/circos -debug -conf tutorials/x/y/circos.conf

This will create high-level summary debug reporting about I/O operations and show you some timings. To generate in-depth debugging of specific components, see the Group Debugging section below.

To create a dump of your configuration, use the -cdump flag

> bin/circos -cdump -conf tutorials/x/y/circos.conf

-cdump is very useful in cases when you are not sure how your configuration files are being parsed. For example, you are receiving errors about parsing a specific parameter, use -cdump to make sure that (a) the parameter is indeed defined and (b) it is defined only once.

You can create a dump of only one part of the configuration tree by providing an argument

# show only the  block
> bin/circos -cdump ideogram

Group Debugging

To obtain debug information about specific components, use -debug_group with one or more of these strings separated by a comma (e.g. -debug_group cache,chrfilter,rule).

angle
anglepos
bezier
brush
cache
chrfilter
color
conf
counter
heatmap
ideogram
image
io
karyotype
layer
link
png
rule
scale
spacing
summary (default)
svg
test
text
textplace
tick
tile
timer
unit
url
zoom

To show debug for all groups, -debug_group _all.

On UNIX, you can use grep to parse out the debug reports for specific groups. For example,

# store all debug output in circos.debug.txt and display only karyotype 
> circos ... -group_debug _all | tee circos.debug.txt | egrep "debuggroup karyotype"
# extract other debug reports
> egrep "debuggroup rule" circos.debug.txt
> egrep "debuggroup (rule|scale)" circos.debug.txt

Benchmarking

If you are concerned about performance, use the timer debug group to turn on timing information. The time taken to execute Circos' components is reported in the following format. Not every part of the code is timed at the moment — this section is likely to expand in the future to include other components. If the image takes more than 30 seconds to run, or if you use -debug_group timer, you will see a list of component timings. For instance, if you run the example

> cd example
> ../bin/circos
debuggroup conf 0.09s welcome to circos 0.56-pre4
debuggroup conf 0.09s guessing configuration file
debuggroup conf 0.12s looking for conf file /home/martink/work/circos/svn/example/etc/circos.conf
debuggroup conf 0.12s found conf file /home/martink/work/circos/svn/example/etc/circos.conf
debuggroup summary 0.42s debug will appear for these features: summary
debuggroup summary 0.42s parsing karyotype and organizing ideograms
debuggroup summary 0.63s applying global and local scaling
debuggroup summary 0.71s allocating image, colors and brushes
debuggroup summary 1.73s drawing highlights and ideograms
debuggroup summary 3.63s drawing link track ratbundle
debuggroup summary 3.63s drawing link track mousebundle
debuggroup summary 3.63s reading data for text track exampledata/genes.txt
debuggroup summary 4.08s placing text track exampledata/genes.txt
debuggroup summary 4.08s ... see progress with -debug_group text
debuggroup summary 4.08s ... see placement summary with -debug_group textplace
debuggroup summary,output 53.12s generating output
debuggroup summary,output 54.10s created PNG image ./circos.png (1946 kb)
debuggroup summary,output 54.11s created SVG image ./circos.svg (876 kb)
debuggroup timer 54.11s report circos 54.019 s
debuggroup timer 54.11s report colorcache 0.005 s
debuggroup timer 54.11s report colordefinitions 0.160 s
debuggroup timer 54.11s report colorlists 0.012 s
debuggroup timer 54.11s report colorlookups 0.005 s
debuggroup timer 54.11s report colortransparency 0.566 s
debuggroup timer 54.11s report datarules 0.344 s
debuggroup timer 54.11s report highlights 0.000 s
debuggroup timer 54.11s report ideograms_draw 1.893 s
debuggroup timer 54.11s report ideograms_processing 0.022 s
debuggroup timer 54.11s report ideograms_ticks_draw 1.545 s
debuggroup timer 54.11s report ideograms_zoom 0.072 s
debuggroup timer 54.11s report io 0.067 s
debuggroup timer 54.11s report karyotype 0.187 s
debuggroup timer 54.11s report parameter_seek 1.800 s
debuggroup timer 54.11s report track_preprocess 0.001 s
debuggroup timer 54.11s report track_text_ashift 39.128 s
debuggroup timer 54.11s report track_text_ashiftiter 19.780 s
debuggroup timer 54.11s report track_text_draw 1.033 s
debuggroup timer 54.11s report track_text_place 47.809 s
debuggroup timer 54.11s report track_text_preashift 7.329 s
debuggroup timer 54.11s report track_text_preprocess 0.568 s
debuggroup timer 54.11s report track_text_refine 0.005 s
debuggroup timer 54.11s report unitconvert 0.022 s
debuggroup timer 54.11s report unitconvert_decision 0.002 s
debuggroup timer 54.11s report unitconvert_delegate 0.008 s
debuggroup timer 54.11s report unitparse 0.031 s
debuggroup summary,timer 54.11s image took more than 30 s to generate. Components timings are
                                shown above. To always show them, use -debug_group timer

Some of the component timing groups are nested. For example, any time spent on ideograms_ticks_draw is included in ideograms_draw.

Keep in mind that extensive debug reporting will slow Circos down.