The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

ggchord:序列图与多视图组合说明

ggchord

按任务选择四个绘图模块,每个模块都提供独立的首图代码。自备数据、专业专题和完整科研案例请继续查阅在线说明。

下载与安装

从 GitHub 安装

从项目仓库安装 ggchord 及必需依赖。源码安装需要可用的 R 开发环境。

install.packages("remotes")
remotes::install_github("DangJem/ggchord", dependencies = NA)

环境与安装检查

需要 R ≥ 4.1.0、ggplot2 ≥ 4.0.0。安装后可查看当前会话实际加载的环境;排查问题时一并提供这些输出。

getRversion()
packageVersion("ggplot2")
packageVersion("ggchord")
find.package("ggchord")

加载与绘制

library(ggchord)

p <- ggchord(seq_data_example) +
  geom_seq() +
  geom_seq_label() +
  coord_chord()
p

成功时应看到四条长度不同、标有序列 ID 的弧形骨架,且没有构建错误。若函数缺失,先检查库路径和会话加载的包,再核对对应函数参考。

可选依赖与输入文件

使用 dplyr、Biostrings 或格式解码器的示例会在代码旁声明依赖,按对应工作流安装即可。随包数据可离线使用;文件示例使用输入归档。

安装失败时

症状 先检查 可操作的处理
无法下载仓库或索引 第一条网络错误、代理与 GitHub 可达性 恢复网络后重试,不先修改示例数据
依赖缺失或版本不足 错误中点名的依赖及 R 下限 安装或更新该依赖,再重试 ggchord
源码编译失败 日志中第一条编译错误、平台构建工具 补齐对应平台 R 开发工具,保留完整日志
安装成功但函数缺失 find.package() 与新会话加载路径 重启 R,确认加载正确库后重试最小图

绘图和输入问题见诊断与排错。

相关说明

绘图基本概念 · 输入数据表 · 保存图形

共用数据与图层

逐步构建骨架、连接、特征和标签。输入来自随包真实记录,按下面顺序运行;需要 ggchord 和可选 dplyr。

绘制骨架

按安装页完成安装后,在全新 R 会话运行本例。

library(ggchord)
p_chord_backbone <- ggchord(seq_data = seq_data_example) +
  geom_seq() +
  geom_seq_label() +
  coord_chord()
view_ggchord(p_chord_backbone, width = 7, height = 7, units = "in")
四条序列的默认弧形骨架
四条序列的默认弧形骨架

读图

每条弧代表序列表的一行。用标签找到 MT108731.1,再与 MT118296.1 比较。它们分别为 64,323 bp 和 32,090 bp,所以第一条弧约为第二条的两倍长。

geom_seq() 画出骨架,geom_seq_label() 标出序列 ID,coord_chord() 把四条骨架排成弧形。

标签层的作用

删除 geom_seq_label() 那一行并重新运行。四条弧会保留,序列名会消失。

加入一个 CDS

选出 OQ646790.1 上从 43,765 bp 开始的原始注释,并取回它的真实链方向。

chord_genes_example <- subset(gene_data_example, accver == "OQ646790.1" & start == 43765)
chord_genes_example$strand <- chord_genes_example$source_strand

p_chord_feature <- p_chord_ribbon +
  geom_gene(data = chord_genes_example)
view_ggchord(p_chord_feature, width = 7, height = 7, units = "in")
在绿色骨架上加入一个 integrase CDS
在绿色骨架上加入一个 integrase CDS

绿色的 OQ646790.1 上出现红色箭头。它是 integrase 的 CDS,范围为 43,765–46,140 bp,原始注释为正链。连接带和这个 CDS 使用各自的数据。

如果需要显示 CDS 名称,可以加上 geom_gene_label(data = chord_genes_example),标签来自 anno 列。

显示特征名称

p_chord_gene_labels <- p_chord_feature +
  geom_gene_label(data = chord_genes_example, label_radial_offset = 0.10)
view_ggchord(p_chord_gene_labels, width = 7, height = 7, units = "in")
保留骨架、连接与 CDS,增加特征名称
保留骨架、连接与 CDS,增加特征名称

切换线性布局

p_chord_linear <- p_chord_gene_labels + coord_collinear()
view_ggchord(p_chord_linear, width = 8, height = 5, units = "in")
Collinear
Collinear

这一步保留连接、CDS 和特征名称图层;线性视图默认只连接相邻行。完整四视图对照见四视图对照。

换成自己的序列

把 seq_data_example 换成含 accver 和 length 的表即可。列的含义见基本数据表。局部参数配置见灵活的参数格式,四种坐标的严格对照见四视图对照。

圆形骨架与已有注释

长度与已有注释

只需要长度与已知表格。本例 ori 行来自已核对 pUC19 注释 867–1455,与原 inspectorigin 输出一致;不运行 DNA 识别。需要 ggchord、dplyr。

library(ggchord)
library(dplyr)
circle_seqs <- plasmid_example_pUC19 |> select(accver, length)
circle_origins <- tibble(
  accver = "pUC19", start = 867, end = 1455,
  strand = "-", type = "rep_origin", anno = "ori"
)
p_coursecircle <- ggchord(circle_seqs) +
  geom_seq() + geom_seq_center_label() + coord_circular()
Circular backbone
Circular backbone

添加特征和标签

p_coursecirclefeature <- p_coursecircle +
  geom_feature_plasmid(data = circle_origins) +
  geom_feature_label(data = circle_origins,
    label_side = "inside", label_radial_offset = 0.12, size = 4)
view_ggchord(p_coursecirclefeature, width = 10, height = 8, units = "in")
Circular feature and label
Circular feature and label

找到 ori 在刻度上的两端,确认文字来自 anno;圆形外观不表示已验证分子拓扑。

调整与保存

去掉标签层再运行,骨架和源区间保持。用自己的已知注释替换该行。

circular_width <- 10
circular_height <- 8
view_ggchord(p_coursecirclefeature,
  width = circular_width, height = circular_height, units = "in")
ggsave("circular-first.png", p_coursecirclefeature,
  width = circular_width, height = circular_height, units = "in", dpi = 144)

HSP 双轴、方向与映射

数据来源、展示子集与重建规则见help("flagship_examples", package = "ggchord")。本页直接加载随包输入,集中设置绘图参数。

本页先用一对序列的真实 HSP 画出双轴线段,再扩展到四序列综合矩阵。最小输入是完整序列长度和 HSP 四端点;无需注释表。

library(ggchord)
library(dplyr)

绘制HSP真实端点

随包数据 sequence_detail_example$paf 保留 EMALE 序列对的11条已观测HSP,来源文件声明的序列长度提供两条轴。 随包表已按一基坐标规范化;反向比对的 target 端点保留降序。 原始文件及来源见输入下载。以下准备代码需要可选依赖dplyr。

library(dplyr)
dotplot_hsp <- sequence_detail_example$paf
dotplot_seqs <- bind_rows(
  dotplot_hsp |> transmute(accver = qaccver, length = qlen),
  dotplot_hsp |> transmute(accver = saccver, length = slen)
) |>
  distinct()

每条线从(qstart, sstart)连接到(qend, send),无需geom_seq()。 颜色、透明度、线宽和线型复用link_*映射与标度。默认Identity范围为0–100, 刻度为0/50/80/90/95/100;显式用户标度优先。

p_viewdotplot <- ggchord(dotplot_seqs, dotplot_hsp) +
  geom_alignment_segment(aes(link_colour = pident), linewidth = 0.65) +
  coord_dotplot()
view_ggchord(p_viewdotplot, width = 8, height = 7, units = "in")
真实EMALE PAF的全部11条HSP,一基原生坐标;反向比对保留负斜率。
真实EMALE PAF的全部11条HSP,一基原生坐标;反向比对保留负斜率。

旧构造验证器可能对这些合法反向HSP的降序端点给出警告。应保留已规范化的端点顺序;逐区间升序排序会抹去显示倒位。

x_seqs和y_seqs分别选择和排列accession。gap使用原生bp/aa单位表示显示留白, 不代表省略源序列。轴方向接受1/-1或完整命名向量。显示翻转改变斜率,但不改来源表。 每条序列从源位置1起算;拼接后的区段保留各自accession和局部刻度标签。

dotplot_reversed <- ggchord(dotplot_seqs, dotplot_hsp) +
  geom_alignment_segment(aes(link_colour = pident), linewidth = 0.65) +
  coord_dotplot(y_orientation = -1)
dotplot_layout <- export_ggchord_layout(dotplot_reversed)
dotplot_layout$axis_layout

用map_ggchord_position(..., axis = "x"/"y")转换原生位置与拼接坐标, inverse = TRUE用于反查,显示间隙返回NA。聚焦后的原始来源坐标用source = TRUE, 轴标签默认仍是窗口相对位置。未知方向会警告、省略并报告;方向元数据与端点冲突时报错。 同一显式HSP ID重复展示需要所有参与层指定allow_repeated=TRUE;无ID的重复或自比对 原行保持独立。没有cg/cs/CIGAR或其他精细轨迹时,只展示HSP线段,不推断逐碱基错配和缺口。

多序列综合矩阵

以下直接使用随包数据 flagship_dotplot_example,计数与标签表已准备完成。完整保留四序列的 32 条 HSP,不补造自比对、对称记录或缺失的 HSP。266 条 CDS 属于共用来源表,但不交给 Dotplot 的线段层。空白区域表示本次输入没有关系记录,不能据此认定不存在同源性。

上方列标题标明 query 序列及完整的 1–length 范围,左侧行标题标明 subject 序列范围;下方和右侧只显示各自序列的局部坐标。沿一列和一行的交点即可定位一对序列。每个带边框的矩形保留两条序列真实长度对应的宽高,淡色背景只帮助分区,不编码相似性。矩形间的留白是显示间隙。

这份输入的 6 个无序序列组合各只提供一个 query→subject 方向,没有反向互换记录,也没有自身比对。因此有 HSP 的区域只占半边;矩阵内标明每对记录数和无输入区域。不是渲染遗漏,也不把另一半留空解释为没有同源性。这里不自动镜像、补对角线或运行新的比对。此准备还使用可选依赖 tidyr。

准备数据与配置(展开)
library(ggchord)
library(dplyr)
flagship_paper <- "#FFFCF5"
flagship_sequences <- flagship_dotplot_example$seq_data
flagship_hsp <- flagship_dotplot_example$links
flagship_theme <- theme_ggchord_publication() +
  theme(
    plot.background = element_rect(fill = flagship_paper, colour = NA),
    panel.background = element_rect(fill = flagship_paper, colour = NA),
    legend.background = element_rect(fill = flagship_paper, colour = NA),
    legend.key = element_rect(fill = flagship_paper, colour = NA),
    legend.position = "right", legend.box = "vertical", legend.text = element_text(size = 8),
    legend.title = element_text(size = 9),
    plot.margin = margin(12, 16, 12, 16)
  )
dotplot_pair_counts <- flagship_dotplot_example$pair_counts
dotplot_cells <- flagship_dotplot_example$cell_labels
flag_dotplot <- ggchord(flagship_sequences, flagship_hsp) +
  geom_alignment_segment(aes(link_colour = pident, link_linewidth = length), alpha = 0.85) +
  scale_link_linewidth_continuous(range = c(0.8, 1.8), name = "HSP length (bp)") +
  coord_dotplot(x_seqs = flagship_sequences$accver, y_seqs = flagship_sequences$accver,
    gap = 4000) +
  ggplot2::geom_text(data = dotplot_cells, aes(x = x, y = y, label = label),
    inherit.aes = FALSE, hjust = 0, vjust = 1, size = 2.8, colour = "#566E67") +
  labs(title = "Six observed sequence pairs · 32 HSPs",
    subtitle = "One query→subject direction per pair; empty cells contain no input records") +
  flagship_theme +
  theme(
    panel.grid = element_blank(), legend.position = "bottom", legend.box = "horizontal",
    axis.text = element_text(size = 9),
    axis.text.x.top = element_text(size = 10, face = "bold", margin = margin(b = 9)),
    axis.text.y.left = element_text(size = 10, face = "bold", margin = margin(r = 9)),
    axis.text.y.right = element_text(size = 9),
    axis.ticks.length = unit(1.5, "mm"),
    plot.margin = margin(12, 16, 12, 16)
  )
四序列 HSP 双轴总览
四序列 HSP 双轴总览 · 完整 R 源码

按来源记录检查方向

四端点的相对方向来自源记录;反转显示轴会改变视觉斜率,但不改原始方向。可以按序列对统计已有 HSP 的方向:

hsp_direction <- flagship_hsp |>
  mutate(relative_direction = if_else(
    (qend - qstart) * (send - sstart) < 0, "reverse", "forward"
  )) |>
  count(qaccver, saccver, relative_direction, name = "HSP")
hsp_direction

查询精确坐标

下面将首条 HSP 的 query 起点换算到拼接 x 轴。反查时用 inverse = TRUE,并明确 axis;显示间隙返回 NA。该转换不改变四端点。

map_ggchord_position(
  flag_dotplot, flagship_hsp$qaccver[1], flagship_hsp$qstart[1], axis = "x"
)

边界与下一步

不支持骨架 gene/feature/track/ribbon 层、facet 或作为 Fusion 端点。需要 gap/mismatch 时,提供真实字符对齐,见字符工作流。操作示例:选一条线,找回四端点,分别解释斜率和配色。

组合面板与真实区间连接

先独立画好两张图

需要 ggchord、dplyr 和随包数据 sequence_detail_example$paf;原始来源可在输入包追溯。先分别打印 course_center 和 course_detail,再组合一条已有关系。

library(ggchord)
library(dplyr)
准备数据与配置(展开)
library(dplyr)
fusion_hsp <- sequence_detail_example$paf
fusion_seqs <- bind_rows(
  fusion_hsp |> transmute(accver = qaccver, length = qlen),
  fusion_hsp |> transmute(accver = saccver, length = slen)
) |>
  distinct()
fusion_colours <- setNames(c("#0072B2", "#D55E00"), fusion_seqs$accver)
fusion_links <- fusion_hsp |>
  filter(length >= 900, pident >= 85)
fusion_events <- fusion_hsp |>
  transmute(accver = qaccver, pos = qstart)
course_center <- ggchord(fusion_seqs |> slice(1)) +
  geom_seq(show.legend = FALSE) +
  coord_circular()
course_detail <- ggchord(fusion_seqs) +
  geom_seq(show.legend = FALSE) +
  geom_seq_label() +
  coord_collinear(seq_axis = "vertical")
p_coursefusion <- ggchord_fusion(course_center) +
  fusion_panel(course_detail, id = "detail", side = "right") +
  fusion_ribbon(
    fusion_links |> slice(1), qpanel = "center", spanel = "detail",
    fill = "#269B82", alpha = 0.35
  )
view_ggchord(p_coursefusion, width = 12, height = 8, units = "in")
独立中心图
独立中心图
独立细节图
独立细节图
Two panels and one source relationship
Two panels and one source relationship

核对区间、面板和实例

Fusion 是组合对象,不是第七 Coord。每个面板保留自己的数据、图层、标度和比例;side 仅摆放,不旋转子图。两端须同单位、完整可见且路由唯一,不能直接连接 bp 与 aa。

fusion_width <- 12
fusion_height <- 8
view_ggchord(p_coursefusion,
  width = fusion_width, height = fusion_height, units = "in")
course_export <- export_ggchord_fusion(p_coursefusion,
  width = fusion_width, height = fusion_height)
course_export$connections
course_export$fronts

按相同尺寸保存

ggsave("fusion-first.png", p_coursefusion,
  width = fusion_width, height = fusion_height, units = "in", dpi = 144)

操作示例:换成另一条真实 HSP,指出 qpanel/spanel 与源行。Dotplot、facet 和未注册外部图当前不支持。

HSP点阵图与径向辐条

复用已有来源表,无需另一套比对表。Dotplot线段保留四个HSP端点,Radial使用已有环形邻接关系和真实长度比例。来源准备、支持图层与位置反查见网站view-expansion章节。

ggchord(seq_data_example, ribbon_data_example) +
  geom_alignment_segment(aes(link_colour = pident)) +
  coord_dotplot()

ggchord(seq_data_example, ribbon_data_example) +
  geom_seq() +
  geom_link_ribbon() +
  geom_seq_label() +
  coord_radial_synteny()

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.