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 のワークフローは通常、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）。

テンプレートの生成には scripts/workflow_generator.py chipseq_analysis を使用します。

完全なコマンドの流れは references/workflows.md の「ChIP-seq Analysis Workflow」にあります。

RNA-seq カバレッジワークフロー

鎖特異的な RNA-seq カバレッジトラックの場合:

--filterRNAstrand を付けた bamCoverage を使って、フォワード鎖とリバース鎖を分離します。

重要: 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" を参照してください

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

BAM/bigWig 処理

BAM を正規化されたカバレッジに変換:

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

2 つのサンプルを比較(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 の比較: log2 と readCount を指定して bamCompare を使用
• RNA-seq のビン: CPM を使用
• RNA-seq の遺伝子: RPKM を使用(遺伝子長を考慮)
• ATAC-seq: RPGC または CPM を使用

正規化手法:

• RPGC: 1× ゲノムカバレッジ(--effectiveGenomeSize が必要)
• CPM: マッピングされたリード 100 万あたりのカウント
• RPKM: キロベースあたり・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 重複を除去(ほとんどの解析で推奨)
• --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
• 重複を除去する: ほとんどの場合 --ignoreDuplicates を使用する
• まずエンリッチメントを確認する: 詳細な解析の前に plotFingerprint を実行する
• GC 補正: 有意なバイアスが検出された場合にのみ適用する。GC 補正後に --ignoreDuplicates を使用しないこと

RNA-seq 固有の注意点

• RNA-seq では リードを延長しない（スプライス接合部をまたいでしまうため）
• 鎖特異的: 鎖特異的ライブラリには --filterRNAstrand forward/reverse を使用する
• 正規化: ビンには CPM、遺伝子には RPKM を使用する

ATAC-seq 固有の注意点

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

パフォーマンスの最適化

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

カテゴリ別に整理された、すべての 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

BAM、bigWig、BED ファイルを deepTools 解析用に検証します。ファイルの存在、インデックス、フォーマットを確認します。

使い方:

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

assets/quick_reference.md

最もよく使うコマンド、有効ゲノムサイズ、一般的なワークフローのパターンをまとめたクイックリファレンスカードです。

使用するタイミング: 詳細なドキュメントを読まずに、コマンドの例だけが必要な場合です。

Handling User Requests

For New Users

1. インストールの確認から始めます
2. scripts/validate_files.py を使って入力ファイルを検証します
3. 実験の種類に応じて適切なワークフローを推奨します
4. scripts/workflow_generator.py を使ってワークフローのテンプレートを生成します
5. カスタマイズと実行をガイドします

For Experienced Users

1. 要求された操作に対して、具体的なツールのコマンドを提示します
2. references/tools_reference.md の該当セクションを参照します
3. 最適化とベストプラクティスを提案します
4. 問題のトラブルシューティングを提供します

For Specific Tasks

「BAM を bigWig に変換する」:

• 適切な正規化を用いて bamCoverage を使用します
• 用途に応じて RPGC または CPM を推奨します
• 生物種に応じた有効ゲノムサイズを提示します
• 関連するパラメータ（extendReads、ignoreDuplicates、binSize）を提案します

「ChIP の品質を確認する」:

• 完全な QC ワークフローを実行するか、plotFingerprint を個別に使用します
• 結果の解釈を説明します
• 結果に基づいて後続の対応を提案します

「ヒートマップを作成する」:

• computeMatrix → plotHeatmap の 2 段階のプロセスをガイドします
• 適切なマトリックスモード（reference-point と scale-regions）の選択を支援します
• 可視化パラメータとクラスタリングのオプションを提案します

「サンプルを比較する」:

• 2 サンプルの比較には bamCompare を推奨します
• 複数サンプルには multiBamSummary + plotCorrelation を提案します
• 正規化手法の選択をガイドします

Referencing Documentation

利用者が詳細な情報を必要とする場合:

• ツールの詳細: 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

Example Interactions

User: 「ChIP-seq データを解析したい」

対応の進め方:

1. 利用可能なファイル（BAM ファイル、ピーク、遺伝子）について尋ねます
2. 検証スクリプトを使ってファイルを検証します
3. chipseq_analysis のワークフローテンプレートを生成します
4. 利用者のファイルと生物種に合わせてカスタマイズします
5. スクリプトの実行に合わせて各ステップを説明します

User: 「どの正規化を使うべきですか？」

対応の進め方:

1. 実験の種類（ChIP-seq、RNA-seq など）について尋ねます
2. 比較の目的（サンプル内か、サンプル間か）について尋ねます
3. references/normalization_methods.md の選択ガイドを参照します
4. 根拠を示したうえで適切な手法を推奨します
5. パラメータを含むコマンドの例を提示します

User: 「TSS の周辺でヒートマップを作成する」

対応の進め方:

1. bigWig ファイルと遺伝子の BED ファイルが利用可能か確認します
2. TSS を基準とした reference-point モードで computeMatrix を使用します
3. 適切な可視化パラメータを指定して plotHeatmap を生成します
4. データセットが大きい場合はクラスタリングを提案します
5. 補完としてプロファイルプロットを提案します

重要なポイント

• ファイル検証を最初に: 解析の前に、必ず入力ファイルを検証してください
• 正規化は重要: 比較の種類に応じて適切な方法を選択してください
• リードの延長は慎重に: ChIP-seq では YES、RNA-seq では NO
• すべてのコアを使用: --numberOfProcessors を利用可能なコア数に設定してください
• 領域でテスト: パラメータのテストには --region を使用してください
• まず QC を確認: 詳細な解析の前に品質管理を実行してください
• すべてを記録: 再現性のために、実行したコマンドを保存してください
• リファレンスドキュメントの参照: 詳細なガイダンスについては、包括的なリファレンスを参照してください