2D 数据绘制（四）
6. 文本标签—Basic
文本标签轨迹将文本字符串与基因组范围相关联。文本是径向放置的，对于散点图，文本的中心线位于跨度的中间。
6.1 数据格式
标签数据文件的格式类似于其他二维数据轨迹
...
hs1 225817866 225910748 ZNF678
hs1 26560711 26571853 ZNF683
hs1 40769819 40786426 ZNF684 color=red
hs1 149521414 149531004 ZNF687
...
第四个字段是文本标签，可选参数放置最后面
6.2 基本文本轨迹
基本文本轨迹定义如下
<plots>
<plot>
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
</plot>
</plots>
默认值
和其他轨迹一样，文本轨迹的参数定义在 etc/tracks/text.conf 文件中
label_font = default
label_size = 12
color = black
r0 = 0.85r
r1 = 0.95r
show_links = no
link_dims = 2p,4p,8p,4p,2p
link_thickness = 1p
link_color = red
padding = 0p
rpadding = 0p
label_snuggle = no
max_snuggle_distance = 1r
snuggle_sampling = 1
snuggle_tolerance = 0.25r
snuggle_refine = no
snuggle_link_overlap_test = no
snuggle_link_overlap_tolerance = 2p
要取消默认定义，可以将指定参数设置为 undef
# undefine color, if you must
color = undef
取消所有默认值
<<include etc/housekeeping.conf>>
track_defaults* = undef
更粗暴点，直接把定义了默认值的文件删除
标签边界和缺失标签
标签限制在内半径 r0 和 外半径 r1 的环形空间内。如果一个标签不能贴在环形空间内，它就不会被画出来。
当标签很大，而轨迹很窄就会发生这种情况。
r0 = 1.05r
r1 = 1.1r
label_size = 100p
要检查标签是否全部放置进图像了，可以在命令行中运行
> circos ... -debug_group textplace
...
debuggroup textplace 2.06s not_placed hs1 10000 20000 gene1
debuggroup textplace 2.06s not_placed hs1 30000 40000 gene2
...
not_placed 的行表示该标签未放置。
为了使标签适应轨迹大小，最简单的方式就是增大 r1。
r0 = 1.05r
r1 = 1.05r+300p
label_size = 100p
6.3 堆叠标签
如果标签与另一个标签的位置发生重叠，为了避免标签绘制的重叠，则标签会在相同的角度但径向位置稍微外移的位置绘制
标签标注线
link_dims 参数指定将标签连接到其基因组位置的线的维度，因为标签可能会移动，所以需要这些连接线。
每个连接线有五个维度：
- 外部填充
- 外部线长度
- 连接线长度
- 内部线长度
- 内部填充
6.4 文本朝向
目前，标签只能朝外，它们的连接线指向圆圈，标签在轨迹半径处左对齐
6.5 文本旋转
通过设置 参数，可以旋转不旋转标签。当标签很短时，非旋转效果很好
<plot>
...
label_rotate = no
</plot>
6.5 刻度标签
当设置 r0=1r 时，标签将绘制在刻度的位置上
<plot>
...
r0 = 1r
r1 = 1r+200p
show_links = yes
link_dims = 0p,0,50p,0p,10p
link_thickness = 2p
link_color = red
</plot>
你需要调整 link_dims 使其足够长，以便将标签移出刻度区域。circos 不检查标签轨迹和刻度标签之间的重叠
7. 文本—堆叠
在前面的例子中，我们只绘制了一个标签，如果标签很密集，则它们会自动堆叠以避免重复
但是，如果设置 label_snuggle=yes，则可以稍微调整标签的径向位置以减少文本的层数
snuggling 是启发式的，不基于任何全局优化
<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>
7.1 snuggling 参数
若要帮助排列标签，以便占用较少的空间，可以使用标签贴合。max_snuggle_distance 可以控制标签在角度方向上移动的距离。
标签会在 max_snuggle_distance 定义的距离之内，每一个 snuggle_sampling 像素进行测试放置位置。
你可以设置 snuggle_tolerance 短路精确放置，该值越大，位置越不精确。
如果标签具有连接线，则可以使用 snuggle_link_overlap_test 测试连接线是否与之前的标签重叠。可以使用 snuggle_link_overlap_tolerance 测试可接受连接程度。
snuggle_refine 参数用于切换对位于相似位置的标签连接线之间的交叉检查。当连接线交叉的标签将被对调。该参数只有当 show_links=yes 才生效。
7.2 标签填充
你可以增加 以使标签布局更加紧凑。也有助于调整标签周围的角度(通过 padding)和径向方向(通过 rpadding)的填充
<plot>
...
padding = 2p
rpadding = 0.1r
</plot>
通过设置填充值为负数，标签之间的距离会更加紧密。当以相对单位是，径向填充相对于标签宽度，而角度填充相对于标签高度
可以通过试验 max_snuggle_distance 和 padding 参数的组合，以找到合适你的数据的组合
7.3 均匀放置文本
如果你想均匀放置文本，请不要使用 snuggling
例如，当标签的密度变化时，snuggling 的效果最好。但是，如果你显示的文本是以特定的间隔定义的，你可能希望关闭连接并使用等宽字体
label_font = mono
所有的字体都定义在 etc/fonts.conf 文件中
# 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
...
7.4 调试文本放置
文本绘制可能需要一段时间，特别是标签比较多的情况下，可以在命令行添加 -debug_group text 参数，看看绘制过程都发生了什么
> 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
...
上面的命令不会监控未放置的文本，可以用 -debug_group textplace 监控哪些标签没有被放置
> 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
...
8. 文本—Rules
可以为每个文本指定规则，规则的使用与前面的教程类似
我们将在图像上绘制一些序列并为碱基对着色，并使用等宽字体
label_font = mono
在此示例中将使用两个数据文件 data/6/sequence.txt
# sequence.txt
...
hs1 2 2 C
hs1 3 3 A
hs1 4 4 A
...
和 data/6/sequence.long.txt
# sequence.long.txt
...
hs1 1 1 A
hs1 1 1 C
hs1 1 1 A
hs1 1 1 G
hs1 2 2 T
hs1 2 2 A
hs1 2 2 C
hs1 2 2 T
...
8.1 应用文本规则
我们将规则保存在一个独立的文件中，保证主配置文件的简洁，同时也使规则能够复用。
<plots>
# default values for all <plot> blocks
type = text
color = black
label_font = mono
label_size = 32
# radial padding
rpadding = 0.2r
<plot>
file = data/6/sequence.txt
r1 = 0.9r
r0 = 0.3r
label_size = 16
# angular padding
padding = -0.25r
<rules>
<<include rule.textcolor.conf>>
</rules>
</plot>
</plots>
rule.textcolor.conf 文件
condition = var(value) eq "A"
color = red
</rule>
<rule>
condition = var(value) eq "T"
color = blue
</rule>
<rule>
condition = var(value) eq "C"
color = green
</rule>
使用 var(value) 引用文本标签，条件检查文本是 A、T 还是 C，并设置不同的颜色。默认的轨迹颜色是标签 G。
8.2 调整文本大小
可以使用规则来调整文本字符的任何属性。例如，可以通过设置 label_size 来调整标签中字母的大小
<rule>
# If the text is not A, then hide it. When this rule triggers,
# other rules are not evaluated.
condition = var(value) ne "A"
show = no
</rule>
# This rule is applied to any text that didn't pass the previous
# rule (i.e. only A). The label is set to a random value between
# 12 and 48. The rand() function returns a uniformly sampled
# random value in the interval [0,1).
<rule>
condition = 1
label_size = eval(12+32*rand())
</rule>
