WGS-All 用户手册

v1.3.0 · 古DNA全基因组分析一体化Docker镜像

安装

系统要求

项目	最低	推荐
Docker	20+	最新版
磁盘	50 GB	100 GB+
内存	4 GB（分析）	16 GB（比对）
系统	Linux / macOS / Windows (Docker Desktop)

加载镜像

# Linux / macOS

docker load < wgs-all.tar

# Windows PowerShell

docker load -i wgs-all.tar

# 验证安装

docker run --rm wgs-all help

下载镜像

镜像文件约 14 GB（tar 格式），加载后约占 45 GB 磁盘空间。

📦 wgs-all.tar (v1.3.0)

百度网盘下载

提取码: k6sk

基本用法

所有命令格式统一：

docker run --rm -v /你的数据目录:/data wgs-all <命令> [参数]

-v /你的数据目录:/data 将本地目录挂载到容器内的 /data，输入输出都在这里。

不需要联网。所有参考数据和工具都内置在镜像里。

比对 (FASTQ → BAM)

将原始测序数据比对到参考基因组。

# hg38 (GRCh38) — 最常用

docker run --rm -v /data:/data wgs-all align SAMPLE R1.fq.gz R2.fq.gz

# hg19 (hs37d5/GRCh37)

docker run --rm -v /data:/data wgs-all align-hg19 SAMPLE R1.fq.gz R2.fq.gz

# T2T (CHM13v2)

docker run --rm -v /data:/data wgs-all align-t2t SAMPLE R1.fq.gz R2.fq.gz

参数：

SAMPLE — 样本名称（输出文件以此命名）
R1.fq.gz — 正向 reads（相对于 /data 的路径）
R2.fq.gz — 反向 reads
可选第四个参数：线程数（默认自动检测全部核心）

输出：

/data/output/SAMPLE/
├── SAMPLE.sorted.bam # 比对结果
├── SAMPLE.sorted.bam.bai # 索引
└── SAMPLE.flagstat.txt # 统计信息

三套参考的区别：

参考	染色体命名	适用场景
hg38	chr1, chrX, chrY, chrM	大多数现代分析
hg19	1, X, Y, MT	兼容旧数据/旧工具
T2T	chr1, chrX, chrY, chrM	最完整参考，含着丝粒

BAM 参考版本识别

docker run --rm -v /data:/data wgs-all detect-bam /data/SAMPLE.sorted.bam

自动识别 BAM 文件对齐到哪个参考基因组。后续命令（extract-chr、extract-chip 等）都会自动调用此功能，通常不需要手动运行。

提取染色体

从全基因组 BAM 中提取特定染色体。

# 提取 Y 染色体

docker run --rm -v /data:/data wgs-all extract-chr /data/SAMPLE.bam chrY -o /data -s SAMPLE

# 提取线粒体

docker run --rm -v /data:/data wgs-all extract-chr /data/SAMPLE.bam chrM -o /data -s SAMPLE

无论 BAM 里染色体叫 chrY 还是 Y，传 chrY 即可，系统自动处理。

输出：

/data/SAMPLE.chrY.bam       # Y 染色体 BAM
/data/SAMPLE.chrY.bam.bai   # 索引
/data/SAMPLE.chrY.vcf.gz    # VCF（变异）

Y 单倍群分析

docker run --rm -v /data:/data wgs-all analyze-y /data/SAMPLE.chrY.bam -o /data/yleaf --tree isogg

参数	说明	默认
`--tree`	系统树：isogg / yfull / yfull_v10 / ftdna	isogg
`--reference`	参考版本：hg38 / hg19 / t2t	自动检测
`--no-adna`	关闭古DNA模式	默认开启

输出示例：

Y 单倍群: N1a2a*(xN1a2a1a)
QC-score: 1.0
使用标记: 5503

需要先用 extract-chr 提取 chrY BAM。覆盖度建议 ≥1x 才有可靠结果。

MT 单倍群分析

docker run --rm -v /data:/data wgs-all analyze-mt /data/SAMPLE.chrM.vcf.gz -o /data/mt.txt

输入 chrM 的 VCF 文件（由 extract-chr 产生）。

输出示例：

MT 单倍群: A11+16234
质量分数: 0.882
变异位点: 15

EIGENSTRAT 数据集导出

古DNA领域标准交付格式，用于 PCA、qpAdm 等群体遗传分析。

# 单个样本

docker run --rm -v /data:/data wgs-all bam-to-eigenstrat \

    --bam /data/SAMPLE.bam \

    -p MyPopulation \

    -o /data/eigenstrat \

    -n dataset_name \

    --deliver-hg19

# 批量（多个样本合并为一个数据集）

docker run --rm -v /data:/data wgs-all bam-to-eigenstrat \

    --bam-list /data/bam_list.txt \

    -p MyPopulation \

    -o /data/eigenstrat \

    -n batch_dataset \

    --deliver-hg19

参数	说明	默认
`--bam`	单个 BAM 文件	—
`--bam-list`	BAM 列表文件（每行一个路径）	—
`-p`	群体标签	必填
`-o`	输出目录	必填
`-n`	数据集名称	必填
`--position-set`	位点集	v42.4.1240K (1.23M位点)
`--deliver-hg19`	额外输出 hg19 坐标版本	不输出
`--seed`	随机种子	42

输出：

/data/eigenstrat/
├── dataset_name.geno       # 基因型矩阵
├── dataset_name.snp        # SNP 信息（hg38 坐标）
├── dataset_name.ind        # 样本信息
├── dataset_name.hg19.geno # hg19 版本（--deliver-hg19）
├── dataset_name.hg19.snp
└── dataset_name.hg19.ind

芯片格式导出

从 BAM 提取基因型，输出 11 种商用芯片格式文件。

docker run --rm -v /data:/data wgs-all extract-chip /data/SAMPLE.bam -o /data/chip -s SAMPLE

自动检测 BAM 参考版本，hg38 BAM 会自动做 LiftOver。

格式	文件名
23andMe V3	SAMPLE_23andMe_V3.txt
23andMe V5	SAMPLE_23andMe_V5.txt
23andMe V35 (合并)	SAMPLE_23andMe_V35.txt
AncestryDNA V1	SAMPLE_Ancestry_V1.txt
AncestryDNA V2	SAMPLE_Ancestry_V2.txt
FTDNA V2	SAMPLE_FTDNA_V2.csv
FTDNA V3	SAMPLE_FTDNA_V3.csv
LivingDNA V1	SAMPLE_LDNA_V1.txt
LivingDNA V2	SAMPLE_LDNA_V2.txt
MyHeritage V1	SAMPLE_MyHeritage_V1.csv
MyHeritage V2	SAMPLE_MyHeritage_V2.csv

用途：上传到 GEDmatch、Vahaduo、exploreyourdna.com 等平台做祖源分析。

祖源计算器

从芯片格式文件计算祖源成分比例。

# 指定计算器

docker run --rm -v /data:/data wgs-all admixture-calc /data/chip/SAMPLE_23andMe_V5.txt -c E11,K36

# 跑全部 28 个

docker run --rm -v /data:/data wgs-all admixture-calc /data/chip/SAMPLE_23andMe_V5.txt

可用计算器（28个）：E11, K12b, K13, K15, K36, K47, globe13, globe10, world9, Jtest, HarappaWorld, EthioHelix, MDLP_World, puntDNAL, Dodecad_World9 等。

输出示例 (E11)：

E11:
  East Chinese: 34.56%
  Southwest Chinese Yi: 30.75%
  South Chinese Dai: 12.01%
  Malay: 11.37%
  North Chinese Oroqen: 5.94%
  ...

G25 距离计算

给定 G25 坐标（25个数字），找到遗传距离最近的人群。

# 直接输入坐标

docker run --rm wgs-all g25 --coords "0.02,-0.015,0.008,-0.01,..." --top 20

# 从文件读取

docker run --rm -v /data:/data wgs-all g25 --file /data/my_coords.csv --top 20

参考数据：10,927 个现代人群 + 1,003 个古代样本。

G25 坐标获取方式：

用 extract-chip 导出 23andMe 格式文件
上传到 exploreyourdna.com 获取坐标
用本命令计算距离

HTML 报告

生成一份总结报告，包含 Y/MT 单倍群、祖源成分、数据产出。

docker run --rm -v /data:/data wgs-all report -s SAMPLE -o /data/report.html \

    --y-hg "N1a2a*(xN1a2a1a)" --y-qc 1.0 \

    --mt-hg "A11+16234" --mt-quality 0.882 \

    --eigen-snps 1231730 --chip-n 11

一键全流程

串联所有分析步骤：提取 chrY/chrM → Y/MT 单倍群 → EIGENSTRAT → 芯片格式 → 祖源计算器。

docker run --rm -v /data:/data wgs-all full-pipeline --bam /data/SAMPLE.bam -o /data/results

工作流：从 FASTQ 开始

# 设置数据目录

DATA=/path/to/data

# 1. 比对

docker run --rm -v $DATA:/data wgs-all align MySample R1.fq.gz R2.fq.gz

# 2. 提取 chrY + chrM

docker run --rm -v $DATA:/data wgs-all extract-chr /data/output/MySample/MySample.sorted.bam chrY -o /data -s MySample

docker run --rm -v $DATA:/data wgs-all extract-chr /data/output/MySample/MySample.sorted.bam chrM -o /data -s MySample

# 3. 单倍群

docker run --rm -v $DATA:/data wgs-all analyze-y /data/MySample.chrY.bam -o /data/yleaf --tree isogg

docker run --rm -v $DATA:/data wgs-all analyze-mt /data/MySample.chrM.vcf.gz -o /data/mt.txt

# 4. EIGENSTRAT

docker run --rm -v $DATA:/data wgs-all bam-to-eigenstrat \

    --bam /data/output/MySample/MySample.sorted.bam -p Han -o /data -n MySample --deliver-hg19

# 5. 芯片格式 + 祖源

docker run --rm -v $DATA:/data wgs-all extract-chip /data/output/MySample/MySample.sorted.bam -o /data/chip -s MySample

docker run --rm -v $DATA:/data wgs-all admixture-calc /data/chip/MySample_23andMe_V5.txt -c E11,K36

工作流：已有 BAM 文件

跳过比对步骤，从第 2 步开始。系统自动检测 BAM 参考版本，无需手动指定。

内置工具

工具	版本	用途
BWA	0.7.19	序列比对
samtools	1.16	BAM 处理
bcftools	1.16	变异检测 / VCF 处理
pileupCaller	1.6.0	古DNA基因型抽取 (randomHaploid)
Yleaf	v4.0.2	Y 染色体单倍群判定
Haplogrep3	3.2.2	线粒体单倍群判定
PLINK	1.9	基因组数据格式转换
ADMIXTURE	1.3	祖源成分估算
smartpca	v16000	主成分分析 (PCA)
ADMIXTOOLS	v810	qpAdm / f-statistics
admix	28 models	祖源计算器

FAQ

支持 Windows 吗？

支持。安装 Docker Desktop (WSL2 后端) 后命令完全一样，路径用 D:\data:/data。

需要联网吗？

不需要。所有参考数据和工具都内置在镜像里。

占多少空间？

镜像文件 14 GB（tar），加载后约 45 GB。运行时内存：分析命令 1-4 GB，比对命令 8-16 GB。

可以同时跑多个样本吗？

可以。开多个 docker run 即可，每个容器独立。注意内存和磁盘 IO。

输出文件权限是 root 怎么办？

系统会自动修复挂载目录的文件权限。如果还有问题，加 -e HOST_UID=$(id -u) -e HOST_GID=$(id -g)。

如何查看所有可用命令？

docker run --rm wgs-all help

AI Agent 集成

如果你使用 Kiro 或其他支持 Skills 的 AI 编程工具，可以下载 WGS-All 的 Skill 文件，让 AI agent 帮你执行分析命令。

使用方法

复制下方的 Skill 文件内容
保存到你项目的 .kiro/skills/wgs-platform/SKILL.md
Agent 就能理解 wgs-all 的所有命令并帮你操作

Skill 文件是一份结构化的知识库，包含所有 CLI 命令、参数、开发构建流程等信息。Agent 读取后就能像专家一样帮你操作 WGS-All。

致谢与引用

本平台集成了以下开源工具和公开数据，感谢原作者的贡献。

工具

工具	License	引用
BWA	GPL-3	Li H. (2013) arXiv:1303.3997
samtools / bcftools	MIT	Danecek P. et al. (2021) GigaScience
pileupCaller	GPL-3	Schiffels S. et al. sequenceTools (GitHub)
Yleaf	MIT	Ralf A. et al. (2024) Forensic Sci Int Genet
Haplogrep3	MIT	Weissensteiner H. et al. (2016) NAR
PLINK	GPL-3	Purcell S. et al. (2007) Am J Hum Genet
ADMIXTURE	Free (academic)	Alexander D. et al. (2009) Genome Res
smartpca / ADMIXTOOLS	Free (academic)	Patterson N. et al. (2006) PLoS Genet
admix	MIT	github.com/stevenliuyi/admix
WGSExtract	GPL-3	wgsextract.github.io（芯片模板数据）

数据

数据	来源
hg38 (GRCh38)	Genome Reference Consortium
hg19 (hs37d5)	1000 Genomes Project
T2T (CHM13v2)	Nurk S. et al. (2022) Science
AADR v42.4 1240K	David Reich Lab
G25 坐标	Davidski / Vahaduo
PhyloTree	van Oven M. (2009) Hum Mutat

许可说明

本平台代码采用 MIT License
集成的 GPL 工具（BWA, pileupCaller, PLINK）：使用其二进制文件不受限制
ADMIXTURE 和 ADMIXTOOLS 仅限学术/非商业使用

如何引用

古基因数据分析平台 (WGS-All) v1.3.0

https://guren.xin

同时请引用上述对应工具的原始论文。

联系与反馈

邮箱: hello@ladydd.com | GitHub Issues: ladydd/wgs-all