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.
7 — 2D Data Tracks
7. Text—Stacking
In the previous example, I had drawn just a few labels. If labels are dense, they will be automatically stacked to avoid overlap. In other words, if a label's position results in overlap with another label, the label is drawn at the same angular position but is radially shifted out.
However, if snuggling is turned on label_snuggle=yes, the
label's radial position may be slightly adjusted to reduce the number
of layers of text.
Snuggling is heuristic—it is not based on any kind of global optimization.
<plot> ... label_snuggle = yes # shift label up to 2x its height in pixels in the angular direction max_snuggle_distance = 2r # sample possible label positions every 2 pixels snuggle_sampling = 2 snuggle_tolerance = 0.25r snuggle_link_overlap_test = yes snuggle_link_overlap_tolerance = 2p snuggle_refine = yes </plot>
snuggling parameters
To help arrange the labels so that they occupy less space, use
label snuggling. The max_snuggle_distance controls
how far the label may be shifted, in the angular direction, to fit
better. The distance limit is expressed in pixels or relative to the
label's size along the tangential direction.
The label is tested at a new angular position every
snuggle_sampling pixels, within the
max_snuggle_distance of its original position. By
increasing the snuggle_sampling value, the layout process
runs faster, but is less precise.
You can also short-circuit precise placement by setting
snuggle_tolerance (absolute or relative to label's
tangential size). The larger this value, the less precise the
placement.
If the labels have a link line, you choose to test whether link
lines overlap with previous labels using
snuggle_link_overlap_test. The extent of acceptable
overlap is set using snuggle_link_overlap_tolerance.
The snuggle_refine parameter toggles an additional check for
crossing of links of labels that are placed at similar radial
positions. Label pairs whose link lines cross are swapped. This refine
parameter is functionaly only if show_links=yes.
label padding
You can increase the max_snuggle_distance to make the label layout
more compact. When snuggling, it can also be helpful to adjust
padding, both angular (via padding) and radial (via rpadding) directions around the label. Both can
be absolute or relative.
<plot> ... padding = 2p rpadding = 0.1r </plot>
By making padding negative, labels are more tightly spaced. When
expressed in relative units (e.g. 0.1r), radial padding is relative to
label width and angular padding is relative to label height.
Experiment with the max_snuggle_distance and padding parameters to
find a good combination for your data. If you have a large number of
labels (hundreds) then the track may take a while to optimize (several
minutes).
uniformly placed text
If you want text to be placed uniformly don't use snuggling, which will move labels around.
For example, snuggling works best when label density varies. But if you're showing text that is defined at specific intervals (e.g. sequence), don't snuggle. You'll probably want to turn links off (this is the default) and use a monospaced font
label_font = mono
All font definitions are in etc/fonts.conf in the Circos distribution.
# etc/fonts.conf ... mono = fonts/modern/cmuntt.ttf # CMUTypewriter-Regular mono_light = fonts/modern/cmunbtl.otf # CMUTypewriter-Light # same as mono and mono_light fixed = fonts/modern/cmuntt.ttf # CMUTypewriter-Regular fixed_light = fonts/modern/cmunbtl.otf # CMUTypewriter-Light ...
debugging text placement
Text placement can take while, especially if snuggling is turned on and you have many labels. Run Circos with -debug_group text to convince yourself that something is happening.
> circos ... -debug_group text ... debuggroup text 6.45s label layer 2 snuggle seek - STX12 8.0 d 26 label_min_height 42 global_min_height 28 debuggroup text 6.45s label layer 2 snuggle seek + PPP1R8 0.0 d 14 label_min_height 42 global_min_height 28 debuggroup text 6.45s label layer 2 snuggle seek - PPP1R8 0.0 d 14 label_min_height 42 global_min_height 28 ...
Text that does not fit into the track boundaries won't be placed. Run Circos with -debug_group textplace to monitor which labels are not placed.
> circos ... -debug_group textplace ... debuggroup textplace 23.02s placed hs1 40858938 40903911 RIMS3 debuggroup textplace 23.02s placed hs1 29346951 29380948 SFRS4 debuggroup textplace 23.03s not_placed hs1 1466916 1500125 SSU72 debuggroup textplace 23.03s placed hs1 27972280 28023550 STX12 debuggroup textplace 23.03s placed hs1 40079314 40121764 TRIT1 ...