deeptools

deepTools：NGS 数据分析工具包

概述

deepTools 是一套全面的 Python 命令行工具，专为处理和分析高通量测序数据而设计。使用 deepTools 可执行质量控制、数据标准化、样本比较，并为 ChIP-seq、RNA-seq、ATAC-seq、MNase-seq 及其他 NGS 实验生成可用于发表的可视化结果。

核心功能：

• 将 BAM 比对结果转换为标准化覆盖度轨迹（bigWig/bedGraph）
• 质量控制评估（指纹图、相关性、覆盖度）
• 样本比较和相关性分析
• 生成基因组特征周围的热图和轮廓图
• 富集分析和峰区域可视化

何时使用此技能

在以下情况下应使用此技能：

• 文件转换：“将 BAM 转换为 bigWig”、“生成覆盖度轨迹”、“标准化 ChIP-seq 数据”
• 质量控制：“检查 ChIP 质量”、“比较重复样本”、“评估测序深度”、“QC 分析”
• 可视化：“创建 TSS 周围的热图”、“绘制 ChIP 信号”、“可视化富集结果”、“生成轮廓图”
• 样本比较：“比较处理组与对照组”、“计算样本间相关性”、“PCA 分析”
• 分析工作流：“分析 ChIP-seq 数据”、“RNA-seq 覆盖度”、“ATAC-seq 分析”、“完整工作流”
• 处理特定文件类型：基因组学场景中的 BAM 文件、bigWig 文件、BED 区域文件

快速入门

刚开始使用 deepTools 的用户，可先验证文件并运行常见工作流：

1. 验证输入文件

运行任何分析之前，请使用验证脚本验证 BAM、bigWig 和 BED 文件：

python scripts/validate_files.py --bam sample1.bam sample2.bam --bed regions.bed

此脚本会检查文件是否存在、BAM 索引以及格式是否正确。

2. 生成工作流模板

对于标准分析，可使用工作流生成器创建自定义脚本：

# List available workflows
python scripts/workflow_generator.py --list

# Generate ChIP-seq QC workflow
python scripts/workflow_generator.py chipseq_qc -o qc_workflow.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398

# Make executable and run
chmod +x qc_workflow.sh
./qc_workflow.sh

3. 最常用的操作

常用命令和参数请参见 assets/quick_reference.md。

安装

uv pip install deeptools

核心工作流

deepTools 工作流通常遵循以下模式：质量控制 → 标准化 → 比较/可视化

ChIP-seq 质量控制工作流

当用户请求 ChIP-seq 质量控制或质量评估时：

1. 使用 scripts/workflow_generator.py chipseq_qc 生成工作流脚本
2. 关键质量控制步骤：
   • 样本相关性（multiBamSummary + plotCorrelation）
   • PCA 分析（plotPCA）
   • 覆盖度评估（plotCoverage）
   • 片段大小验证（bamPEFragmentSize）
   • ChIP 富集强度（plotFingerprint）

结果解读：

• 相关性：重复样本应聚类在一起，且相关性较高（>0.9）
• 指纹图：强 ChIP 信号会陡升；平坦的对角线表示富集效果较差
• 覆盖度：评估测序深度是否足以进行分析

完整工作流详情见 references/workflows.md →“ChIP-seq Quality Control Workflow”

ChIP-seq 完整分析工作流

如需从 BAM 到可视化结果的完整 ChIP-seq 分析：

1. 生成覆盖度轨迹并进行标准化（bamCoverage）
2. 创建比较轨迹（bamCompare，用于计算 log2 比率）
3. 计算特征周围的信号矩阵（computeMatrix）
4. 生成可视化结果（plotHeatmap、plotProfile）
5. 对峰执行富集分析（plotEnrichment）

使用 scripts/workflow_generator.py chipseq_analysis 生成模板。

完整命令序列见 references/workflows.md →“ChIP-seq Analysis Workflow”

RNA-seq 覆盖度工作流

对于链特异性 RNA-seq 覆盖度轨迹：

使用 bamCoverage 和 --filterRNAstrand 分离正向链和反向链。

**重要：**RNA-seq 切勿使用 --extendReads（这会延伸至剪接位点之外）。

标准化方法：固定区间使用 CPM，基因级分析使用 RPKM。

模板见：scripts/workflow_generator.py rnaseq_coverage

详情见 references/workflows.md →“RNA-seq Coverage Workflow”

ATAC-seq 分析工作流

ATAC-seq 需要进行 Tn5 偏移校正：

1. 使用 alignmentSieve 平移 reads，并指定 --ATACshift
2. 使用 bamCoverage 生成覆盖度
3. 分析片段大小（预期出现核小体梯状模式）
4. 如果有 peaks，则进行可视化

模板：scripts/workflow_generator.py atacseq

完整工作流见 references/workflows.md →“ATAC-seq Workflow”

工具类别和常见任务

BAM/bigWig 处理

将 BAM 转换为标准化覆盖度：

bamCoverage --bam input.bam --outFileName output.bw \
    --normalizeUsing RPGC --effectiveGenomeSize 2913022398 \
    --binSize 10 --numberOfProcessors 8

比较两个样本（log2 比值）：

bamCompare -b1 treatment.bam -b2 control.bam -o ratio.bw \
    --operation log2 --scaleFactorsMethod readCount

关键工具： bamCoverage、bamCompare、multiBamSummary、multiBigwigSummary、correctGCBias、alignmentSieve

完整参考见 references/tools_reference.md →“BAM and bigWig File Processing Tools”

质量控制

检查 ChIP 富集：

plotFingerprint -b input.bam chip.bam -o fingerprint.png \
    --extendReads 200 --ignoreDuplicates

样本相关性：

multiBamSummary bins --bamfiles *.bam -o counts.npz
plotCorrelation -in counts.npz --corMethod pearson \
    --whatToShow heatmap -o correlation.png

关键工具： plotFingerprint、plotCoverage、plotCorrelation、plotPCA、bamPEFragmentSize

完整参考见 references/tools_reference.md →“Quality Control Tools”

可视化

创建 TSS 周围的热图：

# Compute matrix
computeMatrix reference-point -S signal.bw -R genes.bed \
    -b 3000 -a 3000 --referencePoint TSS -o matrix.gz

# Generate heatmap
plotHeatmap -m matrix.gz -o heatmap.png \
    --colorMap RdBu --kmeans 3

创建轮廓图：

plotProfile -m matrix.gz -o profile.png \
    --plotType lines --colors blue red

关键工具： computeMatrix、plotHeatmap、plotProfile、plotEnrichment

完整参考见 references/tools_reference.md →“Visualization Tools”

标准化方法

选择正确的标准化方法对于有效比较至关重要。请参阅 references/normalization_methods.md 获取全面指南。

快速选择指南：

• ChIP-seq 覆盖度：使用 RPGC 或 CPM
• ChIP-seq 比较：使用 bamCompare，并设置 log2 和 readCount
• RNA-seq 区间：使用 CPM
• RNA-seq 基因：使用 RPKM（考虑基因长度）
• ATAC-seq：使用 RPGC 或 CPM

标准化方法：

• RPGC：1× 基因组覆盖度（需要 --effectiveGenomeSize）
• CPM：每百万比对 reads 的计数
• RPKM：每 kb、每百万 reads 的 reads 数（考虑区域长度）
• BPM：每百万区间数
• None：原始计数（不建议用于比较）

完整说明：references/normalization_methods.md

有效基因组大小

RPGC 标准化需要有效基因组大小。常见值如下：

生物	组装版本	大小	用法
人类	GRCh38/hg38	2,913,022,398	--effectiveGenomeSize 2913022398
小鼠	GRCm38/mm10	2,652,783,500	--effectiveGenomeSize 2652783500
斑马鱼	GRCz11	1,368,780,147	--effectiveGenomeSize 1368780147
果蝇	dm6	142,573,017	--effectiveGenomeSize 142573017
秀丽隐杆线虫	ce10/ce11	100,286,401	--effectiveGenomeSize 100286401

包含按 read 长度区分的数值的完整表格：references/effective_genome_sizes.md

各工具通用参数

许多 deepTools 命令共用以下选项：

性能：

• --numberOfProcessors, -p：启用并行处理（始终使用可用的核心）
• --region：仅处理特定区域以进行测试（例如，chr1:1-1000000）

Read 过滤：

• --ignoreDuplicates：移除 PCR 重复（大多数分析中建议使用）
• --minMappingQuality：按比对质量过滤（例如，--minMappingQuality 10）
• --minFragmentLength / --maxFragmentLength：片段长度范围
• --samFlagInclude / --samFlagExclude：SAM 标志过滤

Read 处理：

• --extendReads：延伸至片段长度（ChIP-seq：是，RNA-seq：否）
• --centerReads：将片段中心设为中心点，以获得更清晰的信号

最佳实践

文件验证

务必先使用 scripts/validate_files.py 验证文件，检查：

• 文件是否存在且可读
• 是否存在 BAM 索引（.bai 文件）
• BED 格式是否正确
• 文件大小是否合理

分析策略

1. 从 QC 开始：先运行相关性、覆盖度和指纹分析，再继续后续步骤
2. 在小区域进行测试：使用 --region chr1:1-10000000 测试参数
3. 记录命令：保存完整命令行，以便复现
4. 使用一致的标准化方法：比较样本时，对所有样本应用相同的方法
5. 确认基因组组装版本：确保 BAM 和 BED 文件使用匹配的基因组版本

ChIP-seq 专项

• 始终延伸 ChIP-seq 读段：--extendReads 200
• 移除重复读段：大多数情况下使用 --ignoreDuplicates
• 先检查富集情况：详细分析前先运行 plotFingerprint
• GC 校正：仅在检测到显著偏倚时应用；进行 GC 校正后绝不要使用 --ignoreDuplicates

RNA-seq 专项

• 绝不要延伸 RNA-seq 读段（否则会跨越剪接位点）
• 链特异性：对于链特异性文库，使用 --filterRNAstrand forward/reverse
• 标准化：bin 使用 CPM，基因使用 RPKM

ATAC-seq 专项

• 应用 Tn5 校正：使用 alignmentSieve 和 --ATACshift
• 过滤片段：设置合适的片段最小和最大长度
• 检查核小体模式：片段大小图应呈现梯状模式

性能优化

1. 使用多个处理器：--numberOfProcessors 8（或可用的核心数）
2. 增大 bin 大小，以加快处理速度并减小文件体积
3. 在内存受限的系统上按染色体分别处理
4. 使用 alignmentSieve 预先过滤 BAM 文件，生成可重复使用的过滤文件
5. 优先使用 bigWig 而非 bedGraph：压缩率更高，处理速度更快

故障排除

常见问题

缺少 BAM 索引：

samtools index input.bam

内存不足： 使用 --region 按染色体分别处理：

bamCoverage --bam input.bam -o chr1.bw --region chr1

处理速度慢： 增大 --numberOfProcessors 和／或 --binSize

bigWig 文件过大： 增大 bin 大小：--binSize 50 或更大

验证错误

运行验证脚本以识别问题：

python scripts/validate_files.py --bam *.bam --bed regions.bed

脚本输出中说明了常见错误及其解决方法。

参考文档

此技能包含全面的参考文档：

references/tools_reference.md

按类别整理的所有 deepTools 命令完整文档：

• BAM 和 bigWig 处理工具（9 个）
• 质量控制工具（6 个）
• 可视化工具（3 个）
• 杂项工具（2 个）

每个工具都包含：

• 用途和概述
• 关键参数及说明
• 使用示例
• 重要说明和最佳实践

**在以下情况下使用此参考文档：**用户询问特定工具、参数或详细用法时。

references/workflows.md

常见分析的完整工作流示例：

• ChIP-seq 质量控制工作流
• ChIP-seq 完整分析工作流
• RNA-seq 覆盖度工作流
• ATAC-seq 分析工作流
• 多样本比较工作流
• 峰区域分析工作流
• 故障排除和性能提示

**在以下情况下使用此参考文档：**用户需要完整的分析流程或工作流示例时。

references/normalization_methods.md

标准化方法综合指南：

• 各种方法（RPGC、CPM、RPKM、BPM 等）的详细说明
• 各种方法的适用场景
• 公式和解读
• 按实验类型划分的选择指南
• 常见陷阱和解决方法
• 快速参考表

**在以下情况下使用此参考文档：**用户询问标准化、样本比较或应使用哪种方法时。

references/effective_genome_sizes.md

有效基因组大小的数值和用法：

• 常见生物的数值（人、小鼠、果蝇、蠕虫、斑马鱼）
• 特定读长对应的数值
• 计算方法
• 在命令中使用的时机和方法
• 自定义基因组的计算说明

**在以下情况下使用此参考文档：**用户需要 RPGC 标准化或 GC 偏倚校正所用的基因组大小时。

辅助脚本

scripts/validate_files.py

验证用于 deepTools 分析的 BAM、bigWig 和 BED 文件。检查文件是否存在、索引和格式。

用法：

python scripts/validate_files.py --bam sample1.bam sample2.bam \
    --bed peaks.bed --bigwig signal.bw

**适用场景：**开始任何分析之前，或排查错误时。

scripts/workflow_generator.py

为常见的 deepTools 工作流生成可自定义的 bash 脚本模板。

可用工作流：

• chipseq_qc：ChIP-seq 质量控制
• chipseq_analysis：完整的 ChIP-seq 分析
• rnaseq_coverage：链特异性 RNA-seq 覆盖度
• atacseq：使用 Tn5 校正的 ATAC-seq

用法：

# List workflows
python scripts/workflow_generator.py --list

# Generate workflow
python scripts/workflow_generator.py chipseq_qc -o qc.sh \
    --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \
    --genome-size 2913022398 --threads 8

# Run generated workflow
chmod +x qc.sh
./qc.sh

**适用场景：**用户需要标准工作流，或需要可自定义的模板脚本时。

资源

assets/quick_reference.md

速查卡，包含最常用的命令、有效基因组大小和典型工作流模式。

**适用场景：**用户需要快速查看命令示例，而不需要详细文档时。

处理用户请求

面向新用户

1. 从验证安装开始
2. 使用 scripts/validate_files.py 验证输入文件
3. 根据实验类型推荐合适的工作流
4. 使用 scripts/workflow_generator.py 生成工作流模板
5. 指导用户自定义并执行

面向有经验的用户

1. 提供所请求操作的具体工具命令
2. 参阅 references/tools_reference.md 中的相应部分
3. 提出优化建议和最佳实践
4. 针对问题提供故障排查建议

针对具体任务

“将 BAM 转换为 bigWig”：

• 使用 bamCoverage 并选择合适的标准化方法
• 根据使用场景推荐 RPGC 或 CPM
• 提供对应生物的有效基因组大小
• 建议相关参数（extendReads、ignoreDuplicates、binSize）

“检查 ChIP 质量”：

• 运行完整的 QC 工作流，或专门使用 plotFingerprint
• 说明如何解读结果
• 根据结果建议后续操作

“创建热图”：

• 指导用户完成两个步骤：computeMatrix → plotHeatmap
• 帮助选择合适的矩阵模式（reference-point 或 scale-regions）
• 建议可视化参数和聚类选项

“比较样本”：

• 推荐使用 bamCompare 比较两个样本
• 建议使用 multiBamSummary + plotCorrelation 比较多个样本
• 指导选择标准化方法

参考文档

用户需要详细信息时：

• 工具详情：指向 references/tools_reference.md 中的具体部分
• 工作流：使用 references/workflows.md 查看完整分析流程
• 标准化：查阅 references/normalization_methods.md 以选择方法
• 基因组大小：参阅 references/effective_genome_sizes.md

使用 grep 模式搜索参考资料：

# Find tool documentation
grep -A 20 "^### toolname" references/tools_reference.md

# Find workflow
grep -A 50 "^## Workflow Name" references/workflows.md

# Find normalization method
grep -A 15 "^### Method Name" references/normalization_methods.md

示例交互

用户：“我需要分析 ChIP-seq 数据”

回复方式：

1. 询问有哪些可用文件（BAM 文件、峰、基因）
2. 使用验证脚本验证文件
3. 生成 chipseq_analysis 工作流模板
4. 根据用户的具体文件和生物进行自定义
5. 随脚本运行逐步说明每个步骤

用户：“我应该使用哪种标准化方法？”

回复方式：

1. 询问实验类型（ChIP-seq、RNA-seq 等）
2. 询问比较目标（样本内还是样本间）
3. 查阅 references/normalization_methods.md 中的选择指南
4. 说明理由并推荐合适的方法
5. 提供包含参数的命令示例

用户：“创建 TSS 周围的热图”

回复方式：

1. 确认 bigWig 和基因 BED 文件是否可用
2. 使用 computeMatrix，并在 TSS 处采用 reference-point 模式
3. 使用合适的可视化参数生成 plotHeatmap
4. 如果数据集较大，建议进行聚类
5. 提供 profile 图作为补充

关键提醒

• 首先验证文件：分析前始终验证输入文件
• 归一化很重要：根据比较类型选择合适的方法
• 谨慎延伸 reads：ChIP-seq 使用 YES，RNA-seq 使用 NO
• 使用所有核心：将 --numberOfProcessors 设置为可用核心数
• 在区域上测试：使用 --region 测试参数
• 先检查 QC：详细分析前先进行质量控制
• 记录所有内容：保存命令以便复现
• 参考文档：使用全面的参考资料获取详细指导