企业官网建设流程全解析

deepTools 实战指南：基于 scientific-agent-skills 的 NGS 覆盖率、QC 与可视化全流程解析

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

deepTools 是一套面向高通量测序（NGS）数据的 Python 命令行工具套件，本指南以本仓库 skills/deeptools/SKILL.md 为核心，系统讲解其在 ChIP-seq、RNA-seq、ATAC-seq、MNase-seq 等实验中的文件转换、质量控制、样本比较与出版物级可视化流程，并深入配套的 参考文档、辅助脚本 与 测试用例 的源码级实现。读完本文，你将掌握 BAM 转 bigWig 归一化覆盖度、指纹图/相关性/PCA 等 QC 手段、computeMatrix→plotHeatmap/plotProfile 的热图与谱图生成，以及针对不同实验类型的最佳实践与故障排查方案。

概览与核心能力

deepTools 的核心定位是"从比对结果到可解释信号"的一站式处理管线，覆盖以下五大能力（见 SKILL.md）：

• 格式转换：将 BAM 比对文件转换为归一化的覆盖度轨道（bigWig/bedGraph）；
• 质量控制：指纹图（fingerprint）、样本相关性、覆盖度评估；
• 样本比较：样本间相关性分析与 PCA 降维展示；
• 特征区可视化：围绕基因特征（TSS、峰区等）生成热图与谱图；
• 富集分析：峰区信号富集评估与可视化。

何时使用本 Skill

按典型用户诉求分类，deepTools 覆盖以下场景：

快速上手

第一步：校验输入文件

任何分析开始前，都应先用仓库自带的校验脚本 scripts/validate_files.py 检查 BAM、bigWig、BED 文件的完整性与格式正确性：

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

该校验脚本会按文件类型执行分层检查（对应源码validate_files.py中的check_file_exists/check_bam_index/check_bigwig_file/check_bed_file）：

• 文件存在性与可读性：缺失或不可读立即报错；
• BAM 索引：同时兼容.bam.bai与.bai两种命名约定，缺失时提示samtools index input.bam；
• bigWig 合理性：文件大小小于 100 字节视为可疑；
• BED 格式：跳过注释行后要求至少 3 列（chrom、start、end），start 与 end 必须为整数且start < end，否则定位到具体出错行。

校验失败时脚本以非零退出码结束，便于直接接入 CI 或分析管线。

第二步：生成工作流模板

仓库提供了 scripts/workflow_generator.py，可一键生成四种标准工作流的 bash 模板：

# 列出可用工作流 python scripts/workflow_generator.py --list # 生成 ChIP-seq QC 工作流 python scripts/workflow_generator.py chipseq_qc -o qc_workflow.sh \ --input-bam Input.bam --chip-bams "ChIP1.bam ChIP2.bam" \ --genome-size 2913022398 # 赋予执行权限并运行 chmod +x qc_workflow.sh ./qc_workflow.sh

从源码看，workflow_generator.py 的WORKFLOWS字典定义了四类模板：

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

生成的脚本以#!/bin/bash开头并内置set -euo pipefail，任一步骤失败即中止，避免"带错继续跑"的隐性风险。同时脚本生成器对全部用户输入做了安全清洗（sanitize_path只允许[A-Za-z0-9._/-]字符、拒绝..路径穿越，sanitize_positive_int拒绝非正整数，插值时统一走shlex.quote），对应测试见 tests/deeptools/test_scripts.py 中的PathSanitisingTests与ShellQuotingTests。

第三步：常用命令速查

高频命令速查卡见 assets/quick_reference.md，核心模式为：

# BAM 转归一化 bigWig bamCoverage --bam input.bam --outFileName output.bw \ --normalizeUsing RPGC --effectiveGenomeSize 2913022398 \ --binSize 10 --numberOfProcessors 8 # 两样本比较 bamCompare -b1 treatment.bam -b2 control.bam -o ratio.bw \ --operation log2 --scaleFactorsMethod readCount # 相关性热图 multiBamSummary bins --bamfiles *.bam -o counts.npz plotCorrelation -in counts.npz --corMethod pearson \ --whatToShow heatmap -o correlation.png

安装与依赖

仓库的 SKILL.md 声明该 Skill 兼容 Python > 3.8，并固定于 deepTools 3.5.6 兼容的依赖。推荐的安装方式：

# PyPI 安装（仓库示例采用的固定版本路线） uv pip install deepTools==3.5.6

上游项目建议在共享 HPC 等复杂环境下使用 conda/bioconda 以获得完整依赖解析：

conda install -c conda-forge -c bioconda deeptools

Apple Silicon（M 系列）机器上，上游文档提供两种路线：一是使用上述 PyPI 安装，二是当原生 conda 包不可用时创建osx-64架构的 conda 环境。仓库示例之所以使用 uv + 固定 PyPI 版本，是为了保证命令行工作流的可复现性。

归一化方法：比较的前提

归一化是 deepTools 中最容易出错也最关键的环节。不归一化时，1 亿 reads 的样本会天然显得比 5 千万 reads 的样本覆盖度高，即便真实生物信号完全一致。完整理论见 references/normalization_methods.md。

方法速览与快速选型

快速选型原则（也见 SKILL.md）：

• ChIP-seq 覆盖度：RPGC 或 CPM；
• ChIP-seq 比较：bamCompare + log2 操作 + readCount 缩放；
• RNA-seq bin 级：CPM（bin 等长，无需长度校正）；
• RNA-seq 基因级：RPKM（需计入基因长度）；
• ATAC-seq：RPGC 或 CPM。

关键方法要点

RPGC（Reads Per Genomic Content）：以 1× 平均基因组覆盖度为基准缩放。deepTools 将测序深度估计为(总比对 reads × 片段长度) / 有效基因组大小，再取其倒数使信号逼近 1× 覆盖度。信号值 2 约等于 2× 覆盖度，跨样本可比、可解释，是 ChIP-seq/ATAC-seq 的首选；代价是必须提供--effectiveGenomeSize，且当黑名单区域、MAPQ 过滤或去多比对 reads 显著改变可比对空间时，有效基因组大小需要相应调整。

CPM（Counts Per Million）：仅按总比对 reads 缩放，适合固定宽度 bin 的跨样本比较，简单直观；但易受高丰度区域（如 RNA-seq 中的 rRNA）影响。

RPKM（Reads Per Kilobase per Million）：同时校正区域长度与文库大小，适合 RNA-seq 基因级分析；用于等长 bin 时会造成不必要的长度校正，此时应改用 CPM 或 RPGC。

BPM（Bins Per Million）：以"所有 bin 内 reads 之和"为分母（类 TPM 缩放），只关注已分析区域的 reads，忽略区域外背景；与已发表数据的可比性略弱。

SES 与 readCount（bamCompare 专用）：readCount 按两样本总 reads 数比值缩放（如样本 A 100M、样本 B 50M，则 B 放大 2×）；SES（Signal Extraction Scaling）是针对 ChIP-seq 的更精细背景校正方法，对噪声数据通常优于简单 readCount。

高级归一化

spike-in 归一化：基于 spike-in 对照（如 ChIP-seq 中加入果蝇染色质）计算缩放因子后，用--scaleFactor手动施加：

SCALE_FACTOR=0.8 bamCoverage --bam chip.bam --outFileName chip_spikenorm.bw \ --scaleFactor ${SCALE_FACTOR} --extendReads 200

染色体排除：混合性别样本排除性染色体、线粒体等异常覆盖染色体，避免污染归一化计算：

bamCoverage --bam input.bam --outFileName output.bw \ --normalizeUsing RPGC --effectiveGenomeSize 2913022398 \ --ignoreForNormalization chrX chrY chrM

精确缩放：默认 deepTools 会采样 reads 估算过滤后的缩放因子；当过滤模式罕见导致采样估计不准时，使用--exactScaling全量处理 reads 换取精度（更慢但更准）。

常见陷阱

1. bin 级数据用 RPKM：RPKM 校正长度而所有 bin 等长，应改用 CPM 或 RPGC；
2. 比较未归一化样本：2× 测序深度的样本会呈现 2× 假信号；
3. 有效基因组大小用错版本：hg19 数据勿配 hg38 的基因组大小；
4. GC 校正后仍用--ignoreDuplicates：会在 GC 校正后重新引入偏差，禁止混用；
5. RPGC 缺--effectiveGenomeSize：命令直接报错。

有效基因组大小速查表

RPGC 归一化必须指定--effectiveGenomeSize。有效基因组大小指"可比对"基因组长度（能被 reads 唯一比对的区域），计算方法包括非 N 碱基计数与唯一可比对性估算两种，详见 references/effective_genome_sizes.md。

常用物种（非 N 碱基法）

参考文档还提供了按读长区分的可比对性数值（如 hg38 在 50bp 读长时约 27 亿、150bp 时约 29 亿），适用于质量过滤后的数据。当对过滤策略不确定时，保守使用非 N 碱基值适用范围更广。

自定义基因组计算：对自定义组装，可用 UCSC 的faCount或seqtk计算非 N 碱基数：

# faCount（UCSC 工具） faCount genome.fa | grep "total" | awk '{print $2-$7}' # seqtk seqtk comp genome.fa | awk '{x+=$2}END{print x}'

适用位置：bamCoverage --normalizeUsing RPGC、bamCompare --scaleFactorsMethod RPGC、computeGCBias/correctGCBias均需该参数。

核心工作流与工具分类

工作流总览见 references/core_workflows.md，完整命令序列见 references/workflows.md，逐工具参数详解见 references/tools_reference.md。deepTools 流程遵循统一范式：QC → 归一化 → 比较/可视化。

ChIP-seq 质量控制工作流

完整 QC 包含五步（每步命令见 workflows.md）：

1. 初始相关性评估：multiBamSummary bins生成全基因组覆盖矩阵（.npz），随后plotCorrelation输出相关性热图、plotPCA输出主成分图。预期结果：生物学重复应聚类在一起，Input 样本与 ChIP 样本应明显分离；
2. 覆盖度与深度评估：plotCoverage检查测序深度是否满足下游分析需求；
3. 片段大小验证（双端）：bamPEFragmentSize输出片段长度直方图，应与建库方案一致（ChIP-seq 通常 200–600bp）；
4. GC 偏差检测与校正：computeGCBias生成偏差图与频率文件，仅在观察到显著偏差时才用correctGCBias校正；校正后禁用--ignoreDuplicates；
5. ChIP 信号强度评估：plotFingerprint绘制累积覆盖曲线。理想 Input 呈笔直对角线，强 ChIP 样本曲线在最高 rank 处陡峭上升（reads 集中），弱富集则贴近对角线。--outQualityMetrics可导出 Jensen-Shannon 距离等量化指标。

ChIP-seq 完整分析工作流

从 BAM 到出版物级可视化的六步链条：

# 1. 生成归一化覆盖轨道（Input 与 ChIP 各自执行） bamCoverage --bam ChIP.bam --outFileName ChIP_coverage.bw \ --normalizeUsing RPGC --effectiveGenomeSize 2913022398 \ --binSize 10 --extendReads 200 --ignoreDuplicates \ --numberOfProcessors 8 # 2. 创建 log2 比值轨道 bamCompare --bamfile1 ChIP.bam --bamfile2 Input.bam \ --outFileName ChIP_vs_Input_log2ratio.bw \ --operation log2 --scaleFactorsMethod readCount \ --binSize 10 --extendReads 200 --ignoreDuplicates # 3. 计算 TSS 周围信号矩阵 computeMatrix reference-point \ --referencePoint TSS \ --scoreFileName ChIP_coverage.bw \ --regionsFileName genes.bed \ --beforeRegionStartLength 3000 \ --afterRegionStartLength 3000 \ --binSize 10 --sortRegions descend --sortUsing mean \ --outFileName matrix_TSS.gz --outFileNameMatrix matrix_TSS.tab # 4. 生成热图 plotHeatmap --matrixFile matrix_TSS.gz --outFileName heatmap_TSS.png \ --colorMap RdBu --whatToShow 'plot, heatmap and colorbar' \ --zMin -3 --zMax 3 --heatmapHeight 15 --kmeans 3 # 5. 生成谱图（meta-profile） plotProfile --matrixFile matrix_TSS.gz --outFileName profile_TSS.png \ --plotType lines --perGroup --colors blue # 6. 峰区富集评估 plotEnrichment --bamfiles Input.bam ChIP.bam --BED peaks.bed \ --labels Input ChIP --plotFile enrichment.png \ --extendReads 200 --ignoreDuplicates

RNA-seq 覆盖度工作流

链特异性 RNA-seq 使用--filterRNAstrand分离正反链：

# 正链 bamCoverage --bam rnaseq.bam --outFileName forward_coverage.bw \ --filterRNAstrand forward --normalizeUsing CPM \ --binSize 1 --numberOfProcessors 8 # 反链 bamCoverage --bam rnaseq.bam --outFileName reverse_coverage.bw \ --filterRNAstrand reverse --normalizeUsing CPM \ --binSize 1 --numberOfProcessors 8

关键注意：RNA-seq绝不使用--extendReads（会把 reads 跨外显子连接延伸出去）。--filterRNAstrand默认假设常见的 dUTP/NSR/NNSR 反链建库；若文库化学类型不同（read 1 随 RNA 链），正反链输出会颠倒，需改用 SAM flag 过滤并先确认文库方向。

ATAC-seq 工作流

ATAC-seq 需要 Tn5 偏移校正：

# 1. Tn5 偏移校正 alignmentSieve --bam atacseq.bam --outFile atacseq_shifted.bam \ --ATACshift --minFragmentLength 38 --maxFragmentLength 2000 \ --ignoreDuplicates samtools index atacseq_shifted.bam # 2. 生成覆盖轨道 bamCoverage --bam atacseq_shifted.bam --outFileName atacseq_coverage.bw \ --normalizeUsing RPGC --effectiveGenomeSize 2913022398 \ --binSize 1 --numberOfProcessors 8 # 3. 片段大小分析（预期核小体阶梯） bamPEFragmentSize --bamfiles atacseq.bam \ --histogram fragmentSizes_atac.png --maxFragmentLength 1000

--ATACshift等价于--shift 4 -5 5 -4，且只使用 properly paired 片段。片段大小图应呈现核小体阶梯：约 50bp（无核小体区）、约 200bp（单核小体）、约 400bp（双核小体）。

工具分类速览

references/tools_reference.md 将全部工具分为四类：

BAM/bigWig 处理工具（9 个）

包括multiBamSummary（bins/BED-file 两种模式，默认 10kb bin，输出 .npz）、multiBigwigSummary（bigWig 版）、bamCoverage（--outFileFormat bigwig|bedgraph，支持 RPKM/CPM/BPM/RPGC/None 归一化与--smoothLength/--MNase/--Offset/--exactScaling等）、bamCompare（--operation支持 log2/ratio/subtract/add/mean/reciprocal_ratio/first/second，--scaleFactorsMethod支持 readCount/SES/RPKM/CPM/BPM/RPGC，--pseudocount默认 1）、computeGCBias/correctGCBias、alignmentSieve（--BED可输出 BEDPE，--filterMetrics记录过滤前后计数）。注意--shift/--ATACshift均只用 properly paired reads；若在 RPGC 归一化前排除黑名单区域，需相应调整有效基因组大小。

质量控制工具（6 个）

plotFingerprint、plotCoverage（--numberOfSamples默认 1,000,000）、bamPEFragmentSize（--maxFragmentLength默认 1000）、plotCorrelation（Pearson 适合正态分布、Spearman 对异常值稳健；--whatToShow heatmap|scatterplot，--removeOutliers基于 MAD 过滤）、plotPCA（--ntop默认 1000，--PCs默认 1 2，支持--transpose/--log2/--rowCenter）。

可视化工具（3 个）

computeMatrix（reference-point 与 scale-regions 两种模式，--sortRegions/--sortUsing/--averageTypeBins，注意 deepTools 3.x 矩阵含标签、与 3.0 前的绘图工具不兼容）、plotHeatmap（--kmeans/--hclust/--silhouette聚类与--interpolationMethod自动切换 nearest/bilinear）、plotProfile（--plotType lines|fill|se|std|overlapped_lines|heatmap）。

杂项工具（3 个）

bigwigAverage（按 bin 平均多条 bigWig，--scaleFactors用冒号分隔如0.7:1，--skipNonCoveredRegions控制缺失区处理）、computeMatrixOperations（cbind/rbind/subset/filterStrand/filterValues/sort/dataRange）、estimateReadFiltering（采样估算过滤影响，--sampleSize默认 100,000）。

跨工具通用参数

• 性能：--numberOfProcessors, -p开启并行；max/max/2为受支持的取值，近期 deepTools 版本会谨慎探测 CPU 亲和性，在调度器环境下很有用；--region限定处理区域用于测试（如chr1:1-1000000）；
• 读段过滤：--ignoreDuplicates去 PCR 重复（多数分析推荐）；--minMappingQuality按比对质量过滤（如 10）；--minFragmentLength/--maxFragmentLength片段长度边界；--samFlagInclude/--samFlagExcludeSAM flag 过滤；
• 读段处理：--extendReads延伸至片段长度（ChIP-seq 用、RNA-seq 禁用）；--centerReads以片段中点为中心获得更锐利信号。

分实验类型最佳实践

通用策略

1. 先做 QC：相关性、覆盖度、指纹图分析先行；
2. 小区域试跑：用--region chr1:1-10000000调参；
3. 记录命令：完整保存命令行以保证可复现；
4. 归一化保持一致：同一比较中所有样本用同一方法；
5. 核对基因组组装：BAM 与 BED 必须使用同一基因组构建版本。

ChIP-seq 专属

• 始终延伸 reads：--extendReads 200；
• 多数情况去重复：--ignoreDuplicates；
• 先跑plotFingerprint确认富集质量再深入分析；
• GC 校正仅在偏差显著时进行，且 GC 校正后绝不使用--ignoreDuplicates。

RNA-seq 专属

• 绝不延伸 reads（会跨剪接位点）；
• 链特异性文库用--filterRNAstrand forward/reverse，先确认文库方向再解读链标签；
• 归一化：bin 用 CPM，基因用 RPKM。

ATAC-seq 专属

• 用alignmentSieve --ATACshift做 Tn5 校正；
• 仅用 properly paired 片段进行偏移（--ATACshift等价--shift 4 -5 5 -4且过滤为 properly paired）；
• 设置合适的片段长度上下限；
• 用片段大小图核查核小体阶梯模式。

性能优化

1. --numberOfProcessors 8（或可用核数）；
2. 增大 bin size 加速处理、减小文件；
3. 内存受限时按染色体逐条处理（--region chr1）；
4. 用alignmentSieve预过滤 BAM 文件一次成型、多次复用；
5. 优先 bigWig 而非 bedGraph：压缩格式处理更快。

故障排查

常见问题

校验报错

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

脚本输出会明确区分"文件不存在/不可读"、"BAM 索引缺失（含修复命令）"、"bigWig 文件过小"、"BED 列数不足/类型错误/区间反转"等情形（对应 validate_files.py 的各检查函数）。

辅助脚本的使用方式与源码印证

validate_files.py

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

源码要点：check_bam_index同时探测input.bam.bai与input.bai两种命名；check_bed_file只检查前 10 行非注释行即可判定整体格式；validate_files聚合多类型结果，任一失败整体失败。这些行为均有测试覆盖（见 tests/deeptools/test_scripts.py 的FileValidationTests）。

workflow_generator.py

# 列出工作流 python scripts/workflow_generator.py --list # 生成完整 ChIP-seq 分析模板 python scripts/workflow_generator.py chipseq_analysis -o analysis.sh \ --chip-bam H3K4me3.bam --input-bam Input.bam \ --genes-bed genes.bed --peaks-bed peaks.bed --threads 8 # 运行 chmod +x analysis.sh ./analysis.sh

源码要点：每个生成器都输出set -euo pipefail脚本并带mkdir -p建目录；路径参数经sanitize_path/sanitize_path_list清洗、数值经sanitize_positive_int校验后以shlex.quote插值，杜绝 shell 元字符注入。测试GeneratedScriptTests会用bash -n对所有模板做语法解析校验，确保任何模板不会产出不可解析的 bash。

面向不同用户的用法指引

• 新用户：先验证安装 → 校验输入文件 → 按实验类型推荐工作流 → 生成模板 → 引导定制与执行；
• 有经验用户：直接给出具体工具命令、指向工具参考文档的对应章节、提供优化与排障建议；
• 典型任务映射：
  • "Convert BAM to bigWig"：bamCoverage + 合适归一化（按用途推荐 RPGC 或 CPM）+ 有效基因组大小 + extendReads/ignoreDuplicates/binSize 等参数；
  • "Check ChIP quality"：完整 QC 工作流或 plotFingerprint，并解释结果解读与后续动作；
  • "Create heatmap"：computeMatrix（reference-point vs scale-regions）→ plotHeatmap 两步式，配合聚类选项；
  • "Compare samples"：两样本用 bamCompare；多样本用 multiBamSummary + plotCorrelation；并指导归一化选型。

参考文档索引

核心提醒

• 先校验文件：任何分析前先跑 scripts/validate_files.py；
• 归一化决定可比性：按比较类型选对方法；
• 延伸 reads 要谨慎：ChIP-seq 用、RNA-seq 禁用；
• 用满 CPU：--numberOfProcessors设为可用核数；
• 先小区域测试：用--region调参；
• QC 先行：细节分析前先跑质量评估；
• 全程留痕：保存完整命令行保证可复现。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills