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、パイルアップ、リードのフィルタリング	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 は、正しい --transpose、--log2／--rowCenter、 --ntop の処理に対応した scipy/numpy の SVD を使用するようになりました。

主なワークフロー

deepTools のワークフローは通常、次のパターンに従います。QC → 正規化 → 比較／可視化

ChIP-seq 品質管理ワークフロー

ChIP-seq の QC または品質評価を求められた場合：

1. scripts/workflow_generator.py chipseq_qc を使用してワークフロースクリプトを生成します
2. 主な QC 手順：
   • サンプル相関（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）

script/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 を使用してリードをシフトします
2. bamCoverage でカバレッジを生成します
3. フラグメントサイズを解析します（ヌクレオソームのラダー状パターンが予想されます）
4. 利用可能な場合は、ピークで可視化します

テンプレート：scripts/workflow_generator.py atacseq

ワークフロー全体は references/workflows.md →「ATAC-seq Workflow」を参照してください。

ツールのカテゴリーと一般的なタスク

deepTools のコマンドは3つのカテゴリーに分類されます。各カテゴリーのコマンド例は 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：マッピングされたリード100万あたりのカウント数
• RPKM：1 kb・100万リードあたりのリード数（領域長を考慮します）
• BPM：100万あたりのビン数
• 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
Drosophila	dm6	142,573,017	--effectiveGenomeSize 142573017
C. elegans	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 フラグでフィルタリングします

リードの処理：

• --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 が削除されています）。QC ツールでは引き続き --ignoreDuplicates を使用できます
• まずエンリッチメントを確認：詳細な解析の前に plotFingerprint を実行します
• GC 補正：顕著なバイアスが検出された場合にのみ適用し、その後に重複をフィルタリングしないでください。correctGCBias は過少に表現されている領域にリードを追加するため、補正済み BAM から重複を除去すると、まさにその合成リードが破棄され、バイアスが再び生じます

RNA-seq 固有の注意事項

• RNA-seq ではリードを伸長しないでください（スプライスジャンクションをまたいでしまいます）
• 鎖特異的なライブラリ：--filterRNAstrand forward/reverse を使用します
• 正規化：ビンには CPM、遺伝子には RPKM を使用します

ATAC-seq 固有の注意事項

• Tn5 補正を適用：alignmentSieve で --ATACshift を使用します
• フラグメントをフィルタリング：適切な最小／最大フラグメント長を設定します
• ヌクレオソームパターンを確認：フラグメントサイズプロットにラダー状のパターンが表示されるはずです

パフォーマンスの最適化

1. 複数のプロセッサーを使用：--numberOfProcessors 8（または利用可能なコア数）
2. ビンサイズを大きくして、処理を高速化し、ファイルサイズを小さくします
3. メモリに制約のあるシステムでは、染色体ごとに処理します
4. alignmentSieve で BAM ファイルを事前にフィルタリングし、再利用可能なフィルタリング済みファイルを作成します
5. bedGraph より bigWig を使用：圧縮されており、処理が速くなります

トラブルシューティング

よくある問題

BAM インデックスが見つからない：

samtools index input.bam

メモリ不足： --region を使用して、染色体ごとに処理します：

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

処理が遅い： --numberOfProcessors を増やすか、--binSize を大きくしてください

bigWig ファイルが大きすぎる： ビンサイズを大きくします：--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 でフィルタリングしてください。
• リードの延長は慎重に行います：ChIP-seq では --extendReads を使用し、RNA-seq では使用しないでください（スプライスジャンクションをまたいでしまいます）。
• bamCompare では正規化方法を併用できません：RPGC は --normalizeUsing の値です。--scaleFactorsMethod に指定できるのは readCount／SES／None のみです。
• RPGC には --effectiveGenomeSize が必要です。アセンブリが BAM／BED のゲノムビルドと一致していることを確認してください。
• まず QC を確認します（plotFingerprint、相関）。詳細な解析の前に、--region でパラメーターをテストしてください。

AlterLab Academic Skills スイートの一部です。