全站目录 · 按任务查找
数据与坐标
把文件中的观测整理成绘图角色。先检查最小字段与坐标，再使用校验报告决定是否清理；不要为了出图猜测缺失的长度或方向。
本页准备
在新的 R 会话中先运行下方代码，再按页面顺序继续。配色和排版是可选的显示设置，输入只选择需要的列。 涉及文件时，先解压教学输入，使工作目录包含 examples/。
准备代码 · 在本页运行一次
代码
library(ggchord)
library(dplyr)
data(seq_data_example)
data(ribbon_data_example)
data(gene_data_example)
seqs <- seq_data_example |>
select(accver, length)
links <- ribbon_data_example |>
select(qaccver, saccver, qstart, qend, sstart, send)
# The fixture preserves biological strands separately from its old display strands.
genes <- gene_data_example |>
transmute(accver, start, end, strand = source_strand)输入表
| 输入 | 必需字段 | 含义 |
|---|---|---|
| 序列 |
accver, length
|
唯一标识；正值的完整序列长度，单位 bp |
| 区间连接 |
qaccver, saccver, qstart, qend, sstart, send
|
query 与 subject 锚点 |
| 基因 |
accver, start, end, strand
|
链为已知 +/-；anno 可选 |
| 通用注释 |
accver, start, end, strand 或已声明方向 |
可保留未知链；type, label, feature_id 可选 |
标识可以是任意字符串，accession version 原样保留。只有映射、筛选或统计需要时， 才要求 pident 和比对 length。不能由注释的范围推断完整序列长度。
坐标契约
基因组坐标采用 一基、闭区间 bp。BED/PAF 读取器已转换源坐标约定，不要重复转换。 基因起止坐标有序，链单独存储；连接端点的次序可表达方向。没有方向证据的单 bp 连接保持未知。未知链不会被静默改成 +；应使用 geom_feature()，而非严格的基因层。
氨基酸坐标需要显式 CDS 投影。笛卡尔布局单位、基因组 bp、角度、 物理 mm 和轨道数值单位是不同的域。详见完整的数据格式说明。
导入原始记录
在仓库根目录运行这个仅用于源码仓库的例子，不改写原始文件。
代码
seq_files <- read_fasta_lengths(files = "examples/fasta/*.fna", source_file = TRUE)
link_files <- read_blast(files = "examples/blastn-standard/*.tsv", source_file = TRUE)
feature_files <- read_gff3(files = "examples/gff3/*.gff3", unstranded = "keep", source_file = TRUE)read_genbank() 保留记录/注释来源和分段位置。read_bed()、read_paf() 保留 坐标转换元数据。as_ggchord_seq()、as_ggchord_feature()、as_ggchord_link() 适配支持的 S4 对象；对象缺少完整长度或标识时必须显式提供。 file 与 files 均支持路径向量或 glob，重复解析路径按首次出现顺序只读一次。 一个工作流选择一个清晰入口。缺失的序列或同源关系应由分析者 提供，绘图层不生成这些业务数据。
校验、清理与准备
代码
validation <- validate_ggchord_data(seqs, links, genes)
cleaned <- clean_ggchord_data(seqs, links, genes)
prepared <- prepare_ggchord_data(seqs, links, features = list(genes = genes))校验报告问题；清理执行明确修复并返回报告；准备函数组合工作流步骤，不推断生物学 归属。绘图前检查 validation、cleaned$report 和 prepared$report。 几何表的 source_row 指图层已解析输入行，.source_line 才是物理文件行；GenBank 另有记录/注释来源。聚合可带 source_rows 和 .length_estimated，筛选合并时应保留。
检查问题输入及修复报告
代码
# Deliberately corrupt copies to demonstrate diagnostics; original rows remain intact.
problem_links <- ribbon_data_example |>
slice_head(n = 2) |>
select(qaccver, saccver, qstart, qend, sstart, send, pident) |>
mutate(
qaccver = replace(qaccver, 2, "absent"),
pident = replace(pident, 1, 103)
)
problem_report <- validate_ggchord_data(seqs, problem_links)
repaired <- clean_ggchord_data(seqs, problem_links, unknown_id = "drop", invalid_pident = "clip")| 项目 | 结果 |
|---|---|
| 输入行数 | 2 |
| 明确清理后保留的行数 | 1 |
例子只修改原始记录的副本，故意加入未知 ID 和超过 0–100 的相似度。明确修复不表示应该静默 截断科学观测。检查 problem_report、repaired$report，保留原表，并按实际证据 选择策略。合法反向比对可以保持端点顺序，而非排序。prepare_ggchord_data() 因此有其工作流相关的默认策略，不能假定独立清理和准备函数完全相同。
声明 genome 与 contig 键
代码
# Each source record represents a separate complete phage genome.
contigs <- seqs |>
mutate(genome = accver)
genomes <- tibble(genome = seqs$accver)
hierarchy <- validate_ggchord_hierarchy(contigs, genomes, strict = TRUE)hierarchy$contigs 汇总已声明归属，不拼接 contig，也不由 accession 前缀推断归属。 不同样本重复局部 contig 名时须显式提供全局唯一标识。 文件格式与适配器说明格式及可选对象，真实记录教程 把这些报告带入完整绘图流程。
最小输入与蛋白比对
| 项目 | 结果 |
|---|---|
| 传入绘图的序列列数 | 2 |
| 传入绘图的连接列数 | 6 |
| 传入绘图的基因列数 | 4 |
构造函数的第二个位置参数是 ribbon_data，不是 gene_data。建议像共享例子一样 写明参数名，避免把基因表误当成连接表。相似度、比对长度和覆盖率字段只在相应 映射、筛选或统计中才需要。详见标准 BLAST 与蛋白输入和 按序列、按链设置参数。
完成后检查
输入 ID 必须能匹配到完整序列表；原始记录与修复副本分开保存。反向比对端点递减可以合法，不能把所有警告都当作需要删除的数据。