Circos > Documentation > Tutorials > 2d Tracks > Text Labels1

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

6. Text Labels

The text label track associates a text string with a genomic span. The text is placed radially and, as for scatter plots, positioned with its center line at the middle of the span.

Format of labels data files is analogous to other 2D data tracks

hs1 225817866 225910748 ZNF678
hs1 26560711 26571853 ZNF683
hs1 40769819 40786426 ZNF684 color=red
hs1 149521414 149531004 ZNF687

The fourth field is the text label, with optional format parameters specific to the label defined in the last field.

sparse labels

When your labels are sparse and unlikely to overlap with each other, you may turn off label placement optimization, which I call label "snuggling". Snuggling will be covered in the next example.

The basic text track definition is shown below,

type             = text
color            = black
file             = data/6/text.genes.znf.txt

r0 = 0.4r
r1 = 0.8r

show_links     = yes
link_dims      = 4p,4p,8p,4p,4p
link_thickness = 2p
link_color     = red

label_size   = 24p
label_font   = condensed

padding  = 0p
rpadding = 0p


Labels are confined in the annulus of inner radius r0 and outer radius r1. If a label cannot be fit within this annulus, it is not drawn.

The link_dims parameter specifies the dimensions of the lines that link the label to its genomic position. Because labels may be shifted (snuggling, covered in next tutorial), these link lines are necessary. Each link line has five dimensions: outer padding, outer line length (drawn at new position), connecting line length (connects old to new position), inner line length (drawn at old position) and inner padding. If snuggling is not used, then distinction between line lengths is not made.

Labels are drawn so that they do not overlap. 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. If snuggling is turned on, the label's radial position may be slightly adjusted. To control the radial extent of the text track, r0 and r1 are used.

At the moment, labels can only be oriented outwards - their link lines point into the circle and the labels are left-aligned at the track radius.

You can choose to not rotate the labels by setting label_rotate=no (by default, the labels will be rotated to have their baseline oriented radially). The non-rotated option works best when labels are very short (e.g. one character).

label_rotate = no

labels on tick scale

By setting the label radius to r0 = 1, labels are drawn at the position of ticks. Remember that a relative radius of 1 is at the outer ideogram radius.

r0 = 1r
r1 = 1r+200p
show_links     = yes
link_dims      = 0p,0,50p,0p,10p
link_thickness = 2p
link_color     = red

You need to adjust the link_dims so that the link line is long enough to move the label out of the region of the ticks. Circos does not check overlap between elements in the label track and scale ticks.