跳到正文
章节与参考

模块二 · 单序列圆图 · 第 6 节,共 12 节

2.5 圆图标签与避让

下载 R 脚本包含本页准备与全部步骤。文件示例须先下载输入;预览和保存调用保留。
本页目录

用相同六条真实 pUC19 注释比较固定与自动标签。位置、字号、换行与输出尺寸共同影响可读性;文字隐藏不代表注释消失。

1 独立准备本页

需可选依赖 dplyr。原始名称保存在 finish_features,显示文字仅附加真实坐标,不修改注释区间或链。图层读取相同 finish_labels;下面所有图均为 9 × 8 英寸。

R · 示例代码
library(ggchord)
library(dplyr)
finish_dna <- plasmid_example_pUC19
finish_seq <- finish_dna[c("accver", "length")]
finish_features <- head(find_common_features(finish_dna), 6)
finish_circle <- ggchord(finish_seq) + geom_seq() + coord_circular()
finish_labels <- finish_features |>
  mutate(anno = paste0(anno, " [", start, "-", end, " bp]"))
finish_feature_base <- finish_circle + geom_feature(data = finish_labels)

2 固定标签:方向、侧向与旋转

基线 feature 方向跟随特征。后面依次只改为 horizontal、inside 或增加 30 度旋转。只改变一个设置时回到同一基线,不累计上张图的变化。默认 overlap 为 hide,因此拥挤文字可能隐藏。

R · 示例代码
p_comparefixedfeature <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "feature")
view_ggchord(p_comparefixedfeature, width = 9, height = 8, units = "in")
固定标签沿特征方向放置。
固定标签沿特征方向放置。 · 打开高清原图
R · 示例代码
p_comparefixedhorizontal <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "horizontal")
view_ggchord(p_comparefixedhorizontal, width = 9, height = 8, units = "in")
只把固定文字改为横排。
只把固定文字改为横排。 · 打开高清原图
R · 示例代码
p_comparefixedinside <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "feature", label_side = "inside")
view_ggchord(p_comparefixedinside, width = 9, height = 8, units = "in")
只把固定标签放在内侧。
只把固定标签放在内侧。 · 打开高清原图
R · 示例代码
p_comparefixedrotate <- finish_feature_base +
  geom_feature_label(data = finish_labels, label_orientation = "feature", label_rotation = 30)
view_ggchord(p_comparefixedrotate, width = 9, height = 8, units = "in")
只给固定标签增加 30 度旋转。
只给固定标签增加 30 度旋转。 · 打开高清原图

3 固定入口的参数与冲突

参数 默认 意义
label_orientation feature feature/horizontal/radial/tangent;水平与沿特征不同
label_side outside outside/inside/auto
label_overlap hide hide/nudge/allow;allow 可能重叠
label_rotation NULL 额外角度;默认解析为 0
label_radial_offset 0.04 局部法线方向的位移,不是 bp
label_circum_offset NULL 默认 0,沿周向位移
label_circum_limit NULL 默认 TRUE,限制周向位移
label_wrap NULL 可选字符换行宽度

这些固定控制不能传给自动 repel 入口。标签 Position 应与特征一致;子集/重排时优先使用唯一 feature_id,不能让同一 ID 指向不同区间。共线性中的 radial/tangent 对应竖排/横排,不沿圆弧排字。

4 同一文字比较四种自动布局

feature 默认先尝试内部,再尝试相邻与外部;radial、auto、callout 提供不同摆放策略。布局只改变显示,不能新增或删除源注释。四图保留相同输入、请求字号与尺寸。

R · 示例代码
p_comparefeaturefit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature")
view_ggchord(p_comparefeaturefit, width = 9, height = 8, units = "in")
同一批注释,feature 内部优先标签布局。
同一批注释,feature 内部优先标签布局。 · 打开高清原图
R · 示例代码
p_compareradialfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "radial")
view_ggchord(p_compareradialfit, width = 9, height = 8, units = "in")
只改为 radial 布局。
只改为 radial 布局。 · 打开高清原图
R · 示例代码
p_compareautofit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "auto")
view_ggchord(p_compareautofit, width = 9, height = 8, units = "in")
只改为 auto 布局。
只改为 auto 布局。 · 打开高清原图
R · 示例代码
p_comparecalloutfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "callout")
view_ggchord(p_comparecalloutfit, width = 9, height = 8, units = "in")
只改为 callout 布局。
只改为 callout 布局。 · 打开高清原图

5 换行、缩小、隐藏和引线

从 feature 基线出发,先只将 label_fit 改为 shrink,再回到基线只指定 label_wrap=14。shrink 显式允许缩小,最低字号仍为默认 1.5;不能无限缩小来保证每个名称出现。wrap 的字符上限不是固定毫米宽度。

R · 示例代码
p_compareshrinkfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", label_fit = "shrink")
view_ggchord(p_compareshrinkfit, width = 9, height = 8, units = "in")
只将适配策略改为 shrink,字号下限仍为默认 1.5。
只将适配策略改为 shrink,字号下限仍为默认 1.5。 · 打开高清原图
R · 示例代码
p_comparewrapfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", label_wrap = 14)
view_ggchord(p_comparewrapfit, width = 9, height = 8, units = "in")
只指定 14 字符换行宽度,标签文字仍由源名称和坐标组成。
只指定 14 字符换行宽度,标签文字仍由源名称和坐标组成。 · 打开高清原图

以 14 字符换行图为基线,只改 label_fit=ellipsis;随后回到 feature 默认图,只禁用 external。省略或隐藏只改变文字显示,不改源名称或特征。

R · 示例代码
p_compareellipsisfit <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", label_wrap = 14, label_fit = "ellipsis")
view_ggchord(p_compareellipsisfit, width = 9, height = 8, units = "in")
保持 14 字符适配宽度,只改用 ellipsis;完整源名称仍保留。
保持 14 字符适配宽度,只改用 ellipsis;完整源名称仍保留。 · 打开高清原图
R · 示例代码
p_compareexternaloff <- finish_feature_base +
  geom_feature_label_repel(data = finish_labels, label_layout = "feature", external = FALSE)
view_ggchord(p_compareexternaloff, width = 9, height = 8, units = "in")
只禁止外侧回退,无法放下的名称可隐藏,特征仍在。
只禁止外侧回退,无法放下的名称可隐藏,特征仍在。 · 打开高清原图

6 自动入口的重要默认值

参数 默认 选择与限制
label_layout feature feature/radial/auto/callout;gene 布局集合另见通用标签页
label_fit wrap wrap/none/ellipsis/auto/shrink;省略文字不改源表
label_max_lines 2 最大行数;与 wrap 一起检查
label_min_size 1.5 shrink 的字号下限
label_side outside outside/inside/auto
external TRUE FALSE 时不使用外部回退;共线性不支持该约束
max_overlaps Inf 默认不保证完全无碰撞
label_segment_overlap fade 冲突引线的显示策略,默认淡化
label_segment_overlap_alpha 0.18 淡化后的透明度
label_segment_linetype auto 自动选择引线线型
label_segment_layer below below 置于数据层下方;above 恢复标签层顺序,文字位置不变
label_repeat individual bracket 为连续同名短特征添加共享的名称×数量与弧形括注
label_segment_colour auto 圆内特征连圈外标签默认灰色;可指定颜色

诊断表在 export_ggchord_layout 的标签记录中。先读隐藏/适配原因,再调整输出尺寸、标签子集、布局或换行。需要完整源名称时不要只保存截断后的图。

feature 布局使用直接引线,允许穿过特征,不再多折绕路。默认 below 时,正常特征 填充覆盖下方引线;透明填充仍保持透明。内部单行文字沿圆轨道排布,跨原点来源 只保留一条注释,闭合圆上的特征保持连续;有可见开口的坐标仍保留显示分片。相邻标签有明显角向位移时补短引线。 要恢复引线在标签层原有的绘制顺序,可使用

R · 示例代码
geom_feature_label_repel(label_segment_layer = "above")

7 操作示例与自备注释

只把 label_max_lines 改为 3,解释是否改善了拥挤;再固定输出尺寸,比较外部回退开关。固定标签与自动标签有各自接口,不能混用。自备数据用明确 label 文本或 anno,核对 ID、区间、链及唯一 feature_id。继续看引物文字和密集 pETDuet-1 案例。

相邻注释优先比较实际径向距离与角向位移,内侧有空闲轨道时不强迫它们在同一 最近轨道上挤开。箭头中的虚线可能是来源分段或 cleavage 边界,应检查返回的 segments、segment_name 和 cleavage_arrows,不能把每条虚线当作独立特征。 顶层特征标签不会自动为每个子段另加文字;需要子段名称时保留并查看源分段表。

密集内圈注释按来源角度顺序处理,候选位置同时检查文字与引线。引线可穿过 特征,但不为避让其他文字增加多次拐弯;优先另选合法文字位置。启用external 时,外层重复短注释可以成组使用外圈;较内层的特征先尝试内圈,空间不足时仍可回退。该策略是有界搜索, 仍应查看导出中的隐藏、收敛和冲突记录,不保证任意密度都能排入内圈。

8 连续重复特征的共享标注

label_repeat = "bracket" 是显式的显示样式,默认 "individual" 仍逐条标注。 同一特征轨道内,相邻、不重叠、名称、类型、方向和已解析填充一致的短特征, 可共享一个沿弧的“名称 × 数量”和弧形范围括注。中间插入其他注释时不跨过它 合并。各个箭头、坐标和源记录不合并;导出的可见性与适配记录将这些来源标为 represented_by_shared_label。此样式只用于单序列闭合圆的 feature 布局, 其他坐标保持逐条显示。弧形括注是范围标记,标签引线仍使用简单路径。

R · 示例代码
features <- find_common_features(plasmid_example_pTRE_Tight_BI)
feature_position <- position_feature_stack(base_position = position_plasmid())
ggchord(plasmid_example_pTRE_Tight_BI[c("accver", "length")], feature_data = features) +
  geom_seq(seq_style = "double") +
  geom_feature_plasmid(position = feature_position) +
  geom_feature_label_repel(
    position = feature_position,
    label_repeat = "bracket",
    label_fit = "shrink",
    label_min_size = 2.5
  ) +
  coord_circular() +
  theme_ggchord_plasmid()

质粒主题的自动轴文字贴近序列骨架,显式轴偏移不变。圆形特征轨道按不能放入 箭头的文字需求留空,文字轨道按实际字号与物理间隙排布;显式 spacing 仍是 最小间距。这是有界布局,仍需按实际导出尺寸查看诊断,不能保证任意密度无冲突。

默认灰色虚线用于从序列圆内的特征连到圈外标签的引线。圈内相邻标签及限制 位点引线保留原有风格。若圈内名字紧贴自己的特征、角向未明显偏移且无竞争来源, 省略无助于归属的短线;偏移或邻近其他来源时仍保留引线。

R · 示例代码
geom_feature_label_repel(
  label_segment_colour = "grey50",
  label_segment_linetype = "dashed"
)

显式参数调整该图层全部特征引线;自定义 ggchord.feature.label.segment 主题也 优先于自动配色。分段虚线按实际箭头轮廓裁切,保留原分段信息。圈内换行文字的 各行沿各自同心圆逐字排布。自动轴文字保留小的物理留白,显式偏移值仍优先。

拥挤的自动刻度文字只在骨架旁的有限通道内避让。开启 axis.text.check.overlap 时,普通中间刻度没有近环位置可隐藏文字并保留刻度; 原点、终点及接缝组合文字优先保留,不套用这条隐藏规则; 诊断中的 hidden_near_backbone 说明原因,原始刻度值仍在 .axis_label。 隐藏的文字使用空显示字符串,不会把缺失值绘成字面“NA”。

端点仍无法在近环位置解决冲突时,诊断记录 endpoint_unresolved 并保留文字。 外圈特征引线也遵循现有 label_segment_overlap:默认 fade 淡化被文字覆盖的部分, clip 裁掉覆盖部分,show 保留完整线。裁切只分割原来的直线段,不增加绕行拐点。

搜索说明

↑ ↓ 选择 · Enter 打开 · Esc 关闭;也可按任务查找。 API 与功能