visPedigree 1.0.1 cran发布：动物系谱分析与可视化的高效解决方案

visPedigree 1.0.1 cran正式发布。新版本通过 C++ 加速与图论优化重构核心架构，新增高亮追踪、近交系数可视化及矩阵分析工具，显著提升大规模系谱数据处理效率。
R
Visualization
Pedigree
Breeding
Author

Sheng Luan

Published

February 24, 2026

🚀 1.0.0 发布

visPedigree 是一款基于 R 语言开发的系谱分析与可视化工具，旨在解决动植物育种中复杂系谱结构的展示难题。

随着育种群体规模的扩大，传统工具在处理大规模系谱，特别是水产动物大家系系谱时，时常面临计算缓慢、可视化困难等问题。为此，visPedigree 1.0.1 进行了底层架构的全面重构。新版本引入 C++ (Rcpp) 对矩阵运算和近交系数计算等密集型任务进行底层加速，显著提升了计算效率；同时，利用图论算法 (Graph Theory) 优化了系谱整理逻辑，实现了世代自动推断与逻辑错误（如 Loop）的高效检测。

本文将介绍该版本的主要功能更新，包括焦点个体追踪、近交系数可视化及新增的矩阵分析工具。

✨ 主要功能更新

1. 动态焦点追踪 (Focus & Trace)

在大规模群体中，快速定位特定个体及其血缘脉络是系谱分析的常见需求。新版本引入了交互式的 highlight 和 trace 参数，支持对核心个体及其祖先或后代进行针对性展示。

  • highlight: 指定需要高亮显示的“核心个体”。
  • trace: 定义追踪方向。
    • "up": 仅追踪并显示其祖先节点。
    • "down": 仅追踪并显示其后代节点。
    • "all": 同时追踪祖先与后代。
# 安装并加载
# devtools::install_github("luansheng/visPedigree")
library(visPedigree)
data(simple_ped)

# 场景：高亮显示个体 "J5X804" 并追踪其所有祖先
tidy_ped <- tidyped(simple_ped, genmethod = "bottom")
visped(tidy_ped, highlight = "J5X804", trace = "up", cex = 0.5, symbolsize = 10)
Figure 1: 高亮显示个体 J5X804 及其祖先

2. 增强的数据预处理 (tidyped)

tidyped 函数不仅用于数据清洗，现在还集成了强大的诊断与统计功能：

  • 逻辑错误诊断: 利用图论算法自动检测系谱中的死循环 (Loops) 和重复条目。
  • 深度数据摘要: 通过 summary() 方法，提供系谱深度、世代重叠度、每代近交水平等详细统计信息。
  • 系谱修剪 (prune): 自适应保留有效核心群体。
# 检测系谱死循环
try(tidyped(loop_ped))
Error : Pedigree error! Pedigree loops detected:
 M -> P -> R -> T -> V -> M
F -> E -> C -> A -> F
# 数据清洗与近交计算
dt_ped <- tidyped(simple_ped, inbreed = TRUE)

# 查看系谱统计摘要
summary(dt_ped)
Pedigree Summary
================

Total Individuals:  59 
  - Males:    29 (49.2%) 
  - Females:  30 (50.8%) 

Pedigree Structure:
  - Founders (no parents):   28 
  - Both parents known:      28 
  - Sire only known:         2 
  - Dam only known:          1 

Generation:
  - Maximum:  6 
  - Distribution:
      Gen 1: 28 individuals
      Gen 2: 16 individuals
      Gen 3: 8 individuals
      Gen 4: 4 individuals
      Gen 5: 2 individuals
      Gen 6: 1 individuals

Reproduction:
  - Individuals with offspring:  56 
  - Sires:  28  (Mean=1.1, Max=2 offspring)
  - Dams:   28  (Mean=1.0, Max=2 offspring)

Full-sibling Families:
  - Number of families:      27 
  - Mean family size:        1.04
  - Maximum family size:     2 
  - Top families by size:
      J0Z475xJ0C612: 2
      J0C317xJ0C450: 1
      J0C561xJ0C032: 1
      J0C583xJ0Z380: 1
      J0C591xJ0C231: 1

Inbreeding Coefficients:
  - All individuals:
      Mean = 0.0001, Min = 0.0000, Max = 0.0039
      Inbred (f > 0): 1 (1.7%)

================

3. 近交系数可视化 (Inbreeding Visualization)

控制近交水平是制定育种方案的关键。visPedigree 1.0.0 将近交系数 (\(F\)) 的计算与可视化进行了整合。用户可在数据整理阶段直接计算 \(F\) 值，并在绘图时将其直观标注在个体节点上。

  • tidyped(..., inbreed = TRUE): 数据预处理阶段自动计算近交系数。
  • visped(..., showf = TRUE): 绘图时在节点下方标注 \(F\) 值。
# 整理系谱并计算近交系数
DT_ped <- tidyped(simple_ped, inbreed = TRUE)

# 绘图时显示近交系数
visped(DT_ped, showf = TRUE, cex = 0.45, symbolsize = 10)
Figure 2: 在节点中展示近交系数

4. 系谱图压缩模式 (Compact Mode)

在水产育种等高繁殖力物种的场景中，全同胞家系（Full-sib family）往往包含大量个体。如果不加处理直接绘图，图像会横向无限延伸，导致关键结构难以辨识。

visPedigree 提供了 compact = TRUE 参数，专门针对全同胞家系进行了可视化优化。开启该模式后，同一全同胞家系的后代将被“折叠”展示，极大缩减了绘图宽度，使整体系谱结构更加紧凑、清晰。 visPedigree设计函数时，考虑了对管道符|>的支持，简化代码量，逻辑性更强。

# 1. 系谱清洗并自动分割独立群体（GP1 为最大的连通群体）
ped_groups <- big_family_size_ped |> 
  tidyped() |> 
  splitped()

maxi_group <- ped_groups$GP1

# 2. 选取最后 10 个家系的个体作为目标，演示系谱修剪 (Pruning)
# 使用 data.table 的语法确保高效提取
last_10_fams <- tail(unique(maxi_group$Family), 10)
cands <- maxi_group[Family %in% last_10_fams, Ind]

# 3. 提取目标个体的完整血缘脉络，并开启 Compact 模式展示
# Compact 模式会将全同胞家系“折叠”，极大提升了大规模家系的可视化清晰度
maxi_group |> 
  tidyped(cand = cands, genmethod="bottom") |>
  visped(compact = TRUE, cex = 0.3)
Figure 3: 系谱图压缩模式 (Compact Mode)

🛠️ 矩阵分析工具

除核心的可视化功能外，visPedigree 还提供了一系列辅助育种分析的工具函数，支持从系谱数据中提取关键遗传信息。

1. 亲缘关系矩阵计算 (pedmat)

pedmat() 函数利用 C++ 加速，可高效计算亲缘关系矩阵 (Numerator Relationship Matrix, A-Matrix) 或近交系数向量。

它同样支持 compact 参数。在水产育种等场景下，如果不需要针对每个个体计算矩阵，pedmat(..., compact=TRUE) 可以输出全同胞家系层面的亲缘关系矩阵，这将矩阵维度从个体级（数万行）降低到家系级（数百行），极大地节省了内存和后续遗传评估的计算时间。

# 计算个体级稀疏 A 矩阵
A_ind <- pedmat(simple_ped, method = "A", sparse = TRUE)

# 计算家系级压缩 A 矩阵 (Compact Mode)
A_fam <- pedmat(simple_ped, method = "A", compact = TRUE)

2. 矩阵可视化 (vismat)

vismat() 专门用于可视化亲缘关系矩阵。通过热图 (Heatmap) 的形式，直观展示群体内部的亲缘结构，有助于快速识别家系聚类和潜在的近交风险。

# 可视化 A 矩阵
vismat(A_ind, labelsize=0.5)
Figure 4: 利用热图可视化亲缘关系矩阵 (A-Matrix)

💡 快速上手 (Quick Start)

visPedigree 遵循 Tidy Data 原则。无论原始数据是否存在缺失或乱序，tidyped() 均可将其标准化为符合分析要求的格式。

library(visPedigree)
library(data.table)

# 1. 准备示例数据
ped <- data.table(
  ID = c("A", "B", "C", "D", "E"),
  Sire = c(NA, NA, "A", "A", "C"),
  Dam = c(NA, NA, "B", "B", "D")
)

# 2. 数据清洗 (补全、排序、计算近交)
tidy_ped <- tidyped(ped, inbreed = TRUE)

# 3. 可视化展示
visped(tidy_ped, showf = TRUE)
Figure 5: Quick Start 示例输出

快速入手的最便捷途径，是阅读viPedigree包的3个vignette，可以在该包pkgdowns站点的Articles中找到。

📥 获取与反馈

visPedigree 1.0.1 源代码及文档已托管至 GitHub。

visPedigree 1.0.1 已在 CRAN 上发布。

  • CRAN: install.packages("visPedigree")

欢迎使用者通过 GitHub Issue 反馈使用问题或提出功能建议。

Citation: Luan, S. (2026). visPedigree: Visualization and Analysis of Pedigrees. R package version 1.0.1. https://doi.org/10.32614/CRAN.package.visPedigree