alterlab-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 区域文件

不适用的情况

场景	改用
按读取片段访问数据：在 Python 中处理 CIGAR 字符串、MAPQ、pileup 或过滤读取片段	alterlab-pysam
对 BED/峰集合执行区间运算（重叠、Jaccard）或区域嵌入	alterlab-gtars、alterlab-geniml
扫描峰以查找转录因子基序	alterlab-jaspar
统计每个基因的读取片段数以进行差异表达分析	alterlab-rnaseq-quant → alterlab-pydeseq2
从相同的 BAM 文件中进行变异检测	alterlab-nf-core-sarek

快速开始

如果你是 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          # 4.0.0 as of 2026-09 (needs Python >= 3.12)
# or: conda install -c bioconda deeptools

deepTools 4.0 中的变化

bamCoverage、bamCompare、computeMatrix、alignmentSieve 和 multiBamSummary 已 使用 Rust 核心重写（rayon 线程处理、bigtools bigWig I/O）。旧版 Python 实现目前仍以 bamCoverage_old、bamCompare_old、computeMatrix_old、 alignmentSieve_old 和 multiBamSummary_old 的名称保留，计划后续移除。

发生变化的标志及对应替代方案：

4.0 中移除的选项	替代方案
bamCoverage / bamCompare 中的 --ignoreDuplicates	--samFlagExclude 1024（BAM 文件必须已标记重复项，例如通过 samtools markdup 标记）。此标志在 alignmentSieve、plotFingerprint、plotCoverage、multiBamSummary 和 estimateReadFiltering 中仍然有效。
--exactScaling	已移除——新后端始终执行精确缩放
--plotFileFormat plotly 和 plotly 后端	仅支持 matplotlib 输出；--ggplot 可提供类似 ggplot 的主题

此外，Rust 后端工具现在接受经过 gzip 压缩的 GTF/BED 区域文件和黑名单文件， plotPCA 现在使用 scipy/numpy SVD，并能正确处理 --transpose、--log2/--rowCenter 和 --ntop。

核心工作流

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

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. 创建比较轨道（用于 log2 比值的 bamCompare）
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 和 --ATACshift 调整 reads 位置
2. 使用 bamCoverage 生成覆盖度
3. 分析片段大小（预期会呈现核小体梯状模式）
4. 如果有峰，则在峰上进行可视化

模板：scripts/workflow_generator.py atacseq

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

工具类别与常见任务

deepTools 命令分为三类。各类别的快速命令示例见 references/usage_playbook.md → “Inline Command Examples by Category”； 完整参数文档见 references/tools_reference.md。

• BAM/bigWig 处理 — bamCoverage、bamCompare、multiBamSummary、 multiBigwigSummary、correctGCBias、alignmentSieve （tools_reference.md → “BAM and bigWig File Processing Tools”）
• 质量控制 — plotFingerprint、plotCoverage、plotCorrelation、plotPCA、 bamPEFragmentSize（tools_reference.md → “Quality Control Tools”）
• 可视化 — computeMatrix、plotHeatmap、plotProfile、plotEnrichment （tools_reference.md → “Visualization Tools”）

标准化方法

选择正确的标准化方法对于确保比较有效至关重要。请参阅 references/normalization_methods.md，了解完整指南。

快速选择指南：

• ChIP-seq 覆盖度：使用 RPGC 或 CPM
• ChIP-seq 比较：使用采用 log2 和 readCount 的 bamCompare
• RNA-seq 分箱：使用 CPM
• RNA-seq 基因：使用 RPKM（会考虑基因长度）
• ATAC-seq：使用 RPGC 或 CPM

标准化方法：

• RPGC：1× 基因组覆盖度（需要 --effectiveGenomeSize）
• CPM：每百万条比对 reads 的计数
• RPKM：每千碱基、每百万条 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

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

各工具通用参数

许多 deepTools 命令都支持以下选项：

性能：

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

读段筛选：

• --ignoreDuplicates：跳过标记为 PCR 重复的读段。在 4.0 版的 bamCoverage/bamCompare 中不可用——请改用 --samFlagExclude 1024
• --minMappingQuality：按比对质量筛选（例如 --minMappingQuality 10）
• --minFragmentLength / --maxFragmentLength：片段长度范围
• --samFlagInclude / --samFlagExclude：按 SAM flag 筛选

读段处理：

• --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
• 去除重复读段：在 bamCoverage/bamCompare 中使用 --samFlagExclude 1024（4.0 版移除了其中的 --ignoreDuplicates）；--ignoreDuplicates 在 QC 工具中仍可用
• 先检查富集情况：进行详细分析前运行 plotFingerprint
• GC 校正：仅在检测到显著偏差时应用，之后不要筛除重复读段 — correctGCBias 会向代表性不足的区域添加读段，因此在校正后的 BAM 中去除重复读段会恰好丢弃这些合成读段，重新引入偏差

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	用户询问特定工具、参数或详细用法时。包含按类别划分的所有命令（BAM/bigWig 9 个、QC 6 个、可视化 3 个、其他 2 个），以及参数、示例和说明。
references/workflows.md	用户需要完整的分析流程时。包括 ChIP-seq QC、ChIP-seq 分析、RNA-seq 覆盖度、ATAC-seq、多样本比较、峰区域分析和性能建议。
references/normalization_methods.md	用户询问归一化、样本比较或该使用哪种方法时。包括各方法（RPGC/CPM/RPKM/BPM……）的详细信息、公式、选择指南和注意事项。
references/effective_genome_sizes.md	用户需要用于 RPGC 归一化或 GC 偏差校正的基因组大小时。包括按生物体和读长划分的值，以及自定义基因组的计算方法。
references/usage_playbook.md	用户需要操作此技能时：按请求分类的操作指南、交互示例、按类别划分的快速命令示例，以及用于搜索上述参考文档的 grep 配方。

辅助脚本

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

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

使用时机： 用户需要快速查看命令示例，无需详细文档时。

处理用户请求

按请求分类的操作指南（针对新手和有经验的用户，以及针对“将 BAM 转换为 bigWig”“检查 ChIP 质量”“创建热图”“比较样本”等任务的响应）、交互示例，以及用于搜索参考文档的 grep 配方，都位于 references/usage_playbook.md 中。核心流程是： 先验证文件 → 选择合适的工作流/归一化方法 → 生成或运行命令 → 解释结果。

重要提示

• deepTools 4.0：--ignoreDuplicates/--exactScaling 已从 bamCoverage 和 bamCompare 中移除——使用 --samFlagExclude 1024 过滤重复项
• 谨慎延伸 reads：ChIP-seq 使用 --extendReads，RNA-seq 不使用（否则会跨越剪接位点）
• bamCompare 中的归一化方法互斥：RPGC 是 --normalizeUsing 的一个取值；--scaleFactorsMethod 只接受 readCount/SES/None
• RPGC 需要 --effectiveGenomeSize；请确认参考组装与 BAM/BED 的基因组版本相符
• 先检查 QC（plotFingerprint、相关性），再进行详细分析；先在 --region 上测试参数

属于 AlterLab Academic Skills 套件。