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-skillsdeepTools 是一套面向高通量测序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 覆盖以下场景诉求典型说法核心工具文件转换Convert BAM to bigWig、generate coverage tracks、normalize ChIP-seq databamCoverage质量控制check ChIP quality、compare replicates、assess sequencing depthplotFingerprint、plotCorrelation、plotCoverage可视化create heatmap around TSS、plot ChIP signal、generate profile plotcomputeMatrix、plotHeatmap、plotProfile样本比较compare treatment vs control、correlate samples、PCA analysisbamCompare、multiBamSummary、plotPCA完整流程analyze ChIP-seq data、RNA-seq coverage、ATAC-seq analysisworkflow_generator 生成的整套脚本快速上手第一步校验输入文件任何分析开始前都应先用仓库自带的校验脚本 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.bambigWig 合理性文件大小小于 100 字节视为可疑BED 格式跳过注释行后要求至少 3 列chrom、start、endstart 与 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_qcChIP-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 deepTools3.5.6上游项目建议在共享 HPC 等复杂环境下使用 conda/bioconda 以获得完整依赖解析conda install -c conda-forge -c bioconda deeptoolsApple SiliconM 系列机器上上游文档提供两种路线一是使用上述 PyPI 安装二是当原生 conda 包不可用时创建osx-64架构的 conda 环境。仓库示例之所以使用 uv 固定 PyPI 版本是为了保证命令行工作流的可复现性。归一化方法比较的前提归一化是 deepTools 中最容易出错也最关键的环节。不归一化时1 亿 reads 的样本会天然显得比 5 千万 reads 的样本覆盖度高即便真实生物信号完全一致。完整理论见 references/normalization_methods.md。方法速览与快速选型方法校正测序深度校正区域长度最佳适用命令RPKM✓✓RNA-seq 基因表达--normalizeUsing RPKMCPM✓✗固定大小 bin 的比较--normalizeUsing CPMBPM✓✗特定区域信号--normalizeUsing BPMRPGC✓✗可解释的 1× 覆盖度--normalizeUsing RPGC --effectiveGenomeSize XNone✗✗原始数据查看/调试--normalizeUsing NoneSES✓✗ChIP 与对照比较bamCompare --scaleFactorsMethod SESreadCount✓✗ChIP 比较bamCompare 默认bamCompare --scaleFactorsMethod readCount快速选型原则也见 SKILL.mdChIP-seq 覆盖度RPGC 或 CPMChIP-seq 比较bamCompare log2 操作 readCount 缩放RNA-seq bin 级CPMbin 等长无需长度校正RNA-seq 基因级RPKM需计入基因长度ATAC-seqRPGC 或 CPM。关键方法要点RPGCReads Per Genomic Content以 1× 平均基因组覆盖度为基准缩放。deepTools 将测序深度估计为(总比对 reads × 片段长度) / 有效基因组大小再取其倒数使信号逼近 1× 覆盖度。信号值 2 约等于 2× 覆盖度跨样本可比、可解释是 ChIP-seq/ATAC-seq 的首选代价是必须提供--effectiveGenomeSize且当黑名单区域、MAPQ 过滤或去多比对 reads 显著改变可比对空间时有效基因组大小需要相应调整。CPMCounts Per Million仅按总比对 reads 缩放适合固定宽度 bin 的跨样本比较简单直观但易受高丰度区域如 RNA-seq 中的 rRNA影响。RPKMReads Per Kilobase per Million同时校正区域长度与文库大小适合 RNA-seq 基因级分析用于等长 bin 时会造成不必要的长度校正此时应改用 CPM 或 RPGC。BPMBins Per Million以所有 bin 内 reads 之和为分母类 TPM 缩放只关注已分析区域的 reads忽略区域外背景与已发表数据的可比性略弱。SES 与 readCountbamCompare 专用readCount 按两样本总 reads 数比值缩放如样本 A 100M、样本 B 50M则 B 放大 2×SESSignal Extraction Scaling是针对 ChIP-seq 的更精细背景校正方法对噪声数据通常优于简单 readCount。高级归一化spike-in 归一化基于 spike-in 对照如 ChIP-seq 中加入果蝇染色质计算缩放因子后用--scaleFactor手动施加SCALE_FACTOR0.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 换取精度更慢但更准。常见陷阱bin 级数据用 RPKMRPKM 校正长度而所有 bin 等长应改用 CPM 或 RPGC比较未归一化样本2× 测序深度的样本会呈现 2× 假信号有效基因组大小用错版本hg19 数据勿配 hg38 的基因组大小GC 校正后仍用--ignoreDuplicates会在 GC 校正后重新引入偏差禁止混用RPGC 缺--effectiveGenomeSize命令直接报错。有效基因组大小速查表RPGC 归一化必须指定--effectiveGenomeSize。有效基因组大小指可比对基因组长度能被 reads 唯一比对的区域计算方法包括非 N 碱基计数与唯一可比对性估算两种详见 references/effective_genome_sizes.md。常用物种非 N 碱基法物种组装版本有效大小完整命令人GRCh38/hg382,913,022,398--effectiveGenomeSize 2913022398人GRCh37/hg192,864,785,220--effectiveGenomeSize 2864785220人T2T/CHM13CAT_v23,117,292,070--effectiveGenomeSize 3117292070小鼠GRCm39/mm392,654,621,783--effectiveGenomeSize 2654621783小鼠GRCm38/mm102,652,783,500--effectiveGenomeSize 2652783500斑马鱼GRCz111,368,780,147--effectiveGenomeSize 1368780147果蝇dm6142,573,017--effectiveGenomeSize 142573017线虫WBcel235/ce11100,286,401--effectiveGenomeSize 100286401线虫ce10100,258,171--effectiveGenomeSize 100258171拟南芥TAIR10119,482,012--effectiveGenomeSize 119482012参考文档还提供了按读长区分的可比对性数值如 hg38 在 50bp 读长时约 27 亿、150bp 时约 29 亿适用于质量过滤后的数据。当对过滤策略不确定时保守使用非 N 碱基值适用范围更广。自定义基因组计算对自定义组装可用 UCSC 的faCount或seqtk计算非 N 碱基数# faCountUCSC 工具 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初始相关性评估multiBamSummary bins生成全基因组覆盖矩阵.npz随后plotCorrelation输出相关性热图、plotPCA输出主成分图。预期结果生物学重复应聚类在一起Input 样本与 ChIP 样本应明显分离覆盖度与深度评估plotCoverage检查测序深度是否满足下游分析需求片段大小验证双端bamPEFragmentSize输出片段长度直方图应与建库方案一致ChIP-seq 通常 200–600bpGC 偏差检测与校正computeGCBias生成偏差图与频率文件仅在观察到显著偏差时才用correctGCBias校正校正后禁用--ignoreDuplicatesChIP 信号强度评估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 --ignoreDuplicatesRNA-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 个包括multiBamSummarybins/BED-file 两种模式默认 10kb bin输出 .npz、multiBigwigSummarybigWig 版、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、plotCorrelationPearson 适合正态分布、Spearman 对异常值稳健--whatToShow heatmap|scatterplot--removeOutliers基于 MAD 过滤、plotPCA--ntop默认 1000--PCs默认 1 2支持--transpose/--log2/--rowCenter。可视化工具3 个computeMatrixreference-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控制缺失区处理、computeMatrixOperationscbind/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以片段中点为中心获得更锐利信号。分实验类型最佳实践通用策略先做 QC相关性、覆盖度、指纹图分析先行小区域试跑用--region chr1:1-10000000调参记录命令完整保存命令行以保证可复现归一化保持一致同一比较中所有样本用同一方法核对基因组组装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设置合适的片段长度上下限用片段大小图核查核小体阶梯模式。性能优化--numberOfProcessors 8或可用核数增大 bin size 加速处理、减小文件内存受限时按染色体逐条处理--region chr1用alignmentSieve预过滤 BAM 文件一次成型、多次复用优先 bigWig 而非 bedGraph压缩格式处理更快。故障排查常见问题问题解法BAM 索引缺失samtools index input.bam内存不足用--region按染色体处理如bamCoverage --bam input.bam -o chr1.bw --region chr1处理缓慢增大--numberOfProcessors与/或--binSizebigWig 文件过大增大 bin--binSize 50或更大校验报错python scripts/validate_files.py --bam *.bam --bed regions.bed脚本输出会明确区分文件不存在/不可读、BAM 索引缺失含修复命令、bigWig 文件过小、BED 列数不足/类型错误/区间反转等情形对应 validate_files.py 的各检查函数。辅助脚本的使用方式与源码印证validate_files.pypython 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 bigWigbamCoverage 合适归一化按用途推荐 RPGC 或 CPM 有效基因组大小 extendReads/ignoreDuplicates/binSize 等参数Check ChIP quality完整 QC 工作流或 plotFingerprint并解释结果解读与后续动作Create heatmapcomputeMatrixreference-point vs scale-regions→ plotHeatmap 两步式配合聚类选项Compare samples两样本用 bamCompare多样本用 multiBamSummary plotCorrelation并指导归一化选型。参考文档索引文档内容适用场景references/tools_reference.md全部工具按类分组处理 9 个、QC 6 个、可视化 3 个、杂项 3 个含参数与示例查询具体工具/参数/详细用法references/workflows.mdChIP-seq QC、ChIP-seq 完整分析、RNA-seq、ATAC-seq、多样本比较、峰区分析完整命令需要完整分析管线references/normalization_methods.md各归一化方法的公式、适用场景、选型指南与陷阱归一化选型与样本比较references/effective_genome_sizes.md常用物种有效基因组大小、按读长数值与自定义计算RPGC 归一化与 GC 校正references/core_workflows.md核心流程范式与工具分类速览快速理解工作流结构assets/quick_reference.md常用命令、有效基因组大小、典型流程速查卡快速复制常用命令核心提醒先校验文件任何分析前先跑 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 20:14:35 · 阅读 1.2k deepTools 实战指南：基于 scientific-agent-skills 的 NGS 覆盖率、QC 与可视化全流程解析
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-skillsdeepTools 是一套面向高通量测序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 覆盖以下场景诉求典型说法核心工具文件转换Convert BAM to bigWig、generate coverage tracks、normalize ChIP-seq databamCoverage质量控制check ChIP quality、compare replicates、assess sequencing depthplotFingerprint、plotCorrelation、plotCoverage可视化create heatmap around TSS、plot ChIP signal、generate profile plotcomputeMatrix、plotHeatmap、plotProfile样本比较compare treatment vs control、correlate samples、PCA analysisbamCompare、multiBamSummary、plotPCA完整流程analyze ChIP-seq data、RNA-seq coverage、ATAC-seq analysisworkflow_generator 生成的整套脚本快速上手第一步校验输入文件任何分析开始前都应先用仓库自带的校验脚本 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.bambigWig 合理性文件大小小于 100 字节视为可疑BED 格式跳过注释行后要求至少 3 列chrom、start、endstart 与 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_qcChIP-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 deepTools3.5.6上游项目建议在共享 HPC 等复杂环境下使用 conda/bioconda 以获得完整依赖解析conda install -c conda-forge -c bioconda deeptoolsApple SiliconM 系列机器上上游文档提供两种路线一是使用上述 PyPI 安装二是当原生 conda 包不可用时创建osx-64架构的 conda 环境。仓库示例之所以使用 uv 固定 PyPI 版本是为了保证命令行工作流的可复现性。归一化方法比较的前提归一化是 deepTools 中最容易出错也最关键的环节。不归一化时1 亿 reads 的样本会天然显得比 5 千万 reads 的样本覆盖度高即便真实生物信号完全一致。完整理论见 references/normalization_methods.md。方法速览与快速选型方法校正测序深度校正区域长度最佳适用命令RPKM✓✓RNA-seq 基因表达--normalizeUsing RPKMCPM✓✗固定大小 bin 的比较--normalizeUsing CPMBPM✓✗特定区域信号--normalizeUsing BPMRPGC✓✗可解释的 1× 覆盖度--normalizeUsing RPGC --effectiveGenomeSize XNone✗✗原始数据查看/调试--normalizeUsing NoneSES✓✗ChIP 与对照比较bamCompare --scaleFactorsMethod SESreadCount✓✗ChIP 比较bamCompare 默认bamCompare --scaleFactorsMethod readCount快速选型原则也见 SKILL.mdChIP-seq 覆盖度RPGC 或 CPMChIP-seq 比较bamCompare log2 操作 readCount 缩放RNA-seq bin 级CPMbin 等长无需长度校正RNA-seq 基因级RPKM需计入基因长度ATAC-seqRPGC 或 CPM。关键方法要点RPGCReads Per Genomic Content以 1× 平均基因组覆盖度为基准缩放。deepTools 将测序深度估计为(总比对 reads × 片段长度) / 有效基因组大小再取其倒数使信号逼近 1× 覆盖度。信号值 2 约等于 2× 覆盖度跨样本可比、可解释是 ChIP-seq/ATAC-seq 的首选代价是必须提供--effectiveGenomeSize且当黑名单区域、MAPQ 过滤或去多比对 reads 显著改变可比对空间时有效基因组大小需要相应调整。CPMCounts Per Million仅按总比对 reads 缩放适合固定宽度 bin 的跨样本比较简单直观但易受高丰度区域如 RNA-seq 中的 rRNA影响。RPKMReads Per Kilobase per Million同时校正区域长度与文库大小适合 RNA-seq 基因级分析用于等长 bin 时会造成不必要的长度校正此时应改用 CPM 或 RPGC。BPMBins Per Million以所有 bin 内 reads 之和为分母类 TPM 缩放只关注已分析区域的 reads忽略区域外背景与已发表数据的可比性略弱。SES 与 readCountbamCompare 专用readCount 按两样本总 reads 数比值缩放如样本 A 100M、样本 B 50M则 B 放大 2×SESSignal Extraction Scaling是针对 ChIP-seq 的更精细背景校正方法对噪声数据通常优于简单 readCount。高级归一化spike-in 归一化基于 spike-in 对照如 ChIP-seq 中加入果蝇染色质计算缩放因子后用--scaleFactor手动施加SCALE_FACTOR0.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 换取精度更慢但更准。常见陷阱bin 级数据用 RPKMRPKM 校正长度而所有 bin 等长应改用 CPM 或 RPGC比较未归一化样本2× 测序深度的样本会呈现 2× 假信号有效基因组大小用错版本hg19 数据勿配 hg38 的基因组大小GC 校正后仍用--ignoreDuplicates会在 GC 校正后重新引入偏差禁止混用RPGC 缺--effectiveGenomeSize命令直接报错。有效基因组大小速查表RPGC 归一化必须指定--effectiveGenomeSize。有效基因组大小指可比对基因组长度能被 reads 唯一比对的区域计算方法包括非 N 碱基计数与唯一可比对性估算两种详见 references/effective_genome_sizes.md。常用物种非 N 碱基法物种组装版本有效大小完整命令人GRCh38/hg382,913,022,398--effectiveGenomeSize 2913022398人GRCh37/hg192,864,785,220--effectiveGenomeSize 2864785220人T2T/CHM13CAT_v23,117,292,070--effectiveGenomeSize 3117292070小鼠GRCm39/mm392,654,621,783--effectiveGenomeSize 2654621783小鼠GRCm38/mm102,652,783,500--effectiveGenomeSize 2652783500斑马鱼GRCz111,368,780,147--effectiveGenomeSize 1368780147果蝇dm6142,573,017--effectiveGenomeSize 142573017线虫WBcel235/ce11100,286,401--effectiveGenomeSize 100286401线虫ce10100,258,171--effectiveGenomeSize 100258171拟南芥TAIR10119,482,012--effectiveGenomeSize 119482012参考文档还提供了按读长区分的可比对性数值如 hg38 在 50bp 读长时约 27 亿、150bp 时约 29 亿适用于质量过滤后的数据。当对过滤策略不确定时保守使用非 N 碱基值适用范围更广。自定义基因组计算对自定义组装可用 UCSC 的faCount或seqtk计算非 N 碱基数# faCountUCSC 工具 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初始相关性评估multiBamSummary bins生成全基因组覆盖矩阵.npz随后plotCorrelation输出相关性热图、plotPCA输出主成分图。预期结果生物学重复应聚类在一起Input 样本与 ChIP 样本应明显分离覆盖度与深度评估plotCoverage检查测序深度是否满足下游分析需求片段大小验证双端bamPEFragmentSize输出片段长度直方图应与建库方案一致ChIP-seq 通常 200–600bpGC 偏差检测与校正computeGCBias生成偏差图与频率文件仅在观察到显著偏差时才用correctGCBias校正校正后禁用--ignoreDuplicatesChIP 信号强度评估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 --ignoreDuplicatesRNA-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 个包括multiBamSummarybins/BED-file 两种模式默认 10kb bin输出 .npz、multiBigwigSummarybigWig 版、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、plotCorrelationPearson 适合正态分布、Spearman 对异常值稳健--whatToShow heatmap|scatterplot--removeOutliers基于 MAD 过滤、plotPCA--ntop默认 1000--PCs默认 1 2支持--transpose/--log2/--rowCenter。可视化工具3 个computeMatrixreference-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控制缺失区处理、computeMatrixOperationscbind/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以片段中点为中心获得更锐利信号。分实验类型最佳实践通用策略先做 QC相关性、覆盖度、指纹图分析先行小区域试跑用--region chr1:1-10000000调参记录命令完整保存命令行以保证可复现归一化保持一致同一比较中所有样本用同一方法核对基因组组装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设置合适的片段长度上下限用片段大小图核查核小体阶梯模式。性能优化--numberOfProcessors 8或可用核数增大 bin size 加速处理、减小文件内存受限时按染色体逐条处理--region chr1用alignmentSieve预过滤 BAM 文件一次成型、多次复用优先 bigWig 而非 bedGraph压缩格式处理更快。故障排查常见问题问题解法BAM 索引缺失samtools index input.bam内存不足用--region按染色体处理如bamCoverage --bam input.bam -o chr1.bw --region chr1处理缓慢增大--numberOfProcessors与/或--binSizebigWig 文件过大增大 bin--binSize 50或更大校验报错python scripts/validate_files.py --bam *.bam --bed regions.bed脚本输出会明确区分文件不存在/不可读、BAM 索引缺失含修复命令、bigWig 文件过小、BED 列数不足/类型错误/区间反转等情形对应 validate_files.py 的各检查函数。辅助脚本的使用方式与源码印证validate_files.pypython 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 bigWigbamCoverage 合适归一化按用途推荐 RPGC 或 CPM 有效基因组大小 extendReads/ignoreDuplicates/binSize 等参数Check ChIP quality完整 QC 工作流或 plotFingerprint并解释结果解读与后续动作Create heatmapcomputeMatrixreference-point vs scale-regions→ plotHeatmap 两步式配合聚类选项Compare samples两样本用 bamCompare多样本用 multiBamSummary plotCorrelation并指导归一化选型。参考文档索引文档内容适用场景references/tools_reference.md全部工具按类分组处理 9 个、QC 6 个、可视化 3 个、杂项 3 个含参数与示例查询具体工具/参数/详细用法references/workflows.mdChIP-seq QC、ChIP-seq 完整分析、RNA-seq、ATAC-seq、多样本比较、峰区分析完整命令需要完整分析管线references/normalization_methods.md各归一化方法的公式、适用场景、选型指南与陷阱归一化选型与样本比较references/effective_genome_sizes.md常用物种有效基因组大小、按读长数值与自定义计算RPGC 归一化与 GC 校正references/core_workflows.md核心流程范式与工具分类速览快速理解工作流结构assets/quick_reference.md常用命令、有效基因组大小、典型流程速查卡快速复制常用命令核心提醒先校验文件任何分析前先跑 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考