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==3.5.6

アップストリームでは、特に共有HPCシステムで依存関係をすべて解決するため、conda/biocondaの使用を推奨しています。

conda install -c conda-forge -c bioconda deeptools

Apple Siliconでは、ネイティブのcondaパッケージを利用できない場合、アップストリームのドキュメントに記載された上記のPyPI経由の方法、またはosx-64 conda環境を利用できます。

主なワークフローとツールのカテゴリ

ChIP-seq QC、ChIP-seqの全工程解析、RNA-seqカバレッジ、ATAC-seq解析の一連のコマンドに加え、BAM/bigWigの処理、品質管理、可視化のツールカテゴリについては、references/core_workflows.mdおよびreferences/workflows.mdを参照してください。各ツールのオプションについては、references/tools_reference.mdを参照してください。

正規化手法

適切な正規化手法を選択することは、妥当な比較を行ううえで非常に重要です。詳しいガイダンスについては、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万ビンあたりのビン数。ビン分割したシグナルに対するTPM形式のスケーリングに相当します
• None：生のカウント数（比較には推奨されません）

詳しい説明：references/normalization_methods.md

有効ゲノムサイズ

RPGC 正規化には、有効ゲノムサイズが必要です。一般的な値は次のとおりです。

生物	アセンブリ	サイズ	使用方法
ヒト	GRCh38/hg38	2,913,022,398	--effectiveGenomeSize 2913022398
ヒト	T2T/CHM13CAT_v2	3,117,292,070	--effectiveGenomeSize 3117292070
マウス	GRCm39/mm39	2,654,621,783	--effectiveGenomeSize 2654621783
マウス	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：並列処理を有効にします（常に利用可能なコアを使用してください）
• max / max/2：--numberOfProcessors でサポートされている値です。最近の deepTools リリースでは CPU アフィニティがより慎重に検出されるため、スケジューラーの使用時に便利です
• --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 ではリードを延長しないでください（スプライスジャンクションをまたいでしまいます）
• 鎖特異的解析：一般的な dUTP 方式の鎖特異的ライブラリには --filterRNAstrand forward/reverse を使います。鎖ラベルを解釈する前に、ライブラリの向きを確認してください
• 正規化：ビンには CPM、遺伝子には RPKM を使います

ATAC-seq 固有の注意事項

• Tn5 補正を適用する：alignmentSieve と --ATACshift を使います
• シフトには適切なペアのみを使う：--ATACshift は --shift 4 -5 5 -4 と同等で、適切にペアリングされたフラグメントに絞り込みます
• フラグメントをフィルタリングする：適切な最小／最大フラグメント長を設定します
• ヌクレオソームパターンを確認する：フラグメントサイズプロットにラダー状のパターンが表示されるはずです

パフォーマンスの最適化

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 個）
• その他のツール（3 個。bigwigAverage を含む）

各ツールには、次の内容が含まれています：

• 目的と概要
• 主なパラメーターの説明
• 使用例
• 重要な注意事項とベストプラクティス

このリファレンスを使用する場合： ユーザーが特定のツール、パラメーター、または詳細な使用方法について質問したとき。

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

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

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

使用するタイミング： ユーザーが詳細なドキュメントなしで、コマンドの使用例をすぐに確認したいとき。

ユーザーリクエストへの対応

初心者の場合

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

経験者の場合

1. 依頼された操作に対応する具体的なツールコマンドを提示します
2. references/tools_reference.md の該当箇所を参照します
3. 最適化とベストプラクティスを提案します
4. 問題のトラブルシューティングを支援します

特定のタスク向け

「BAM を bigWig に変換する」：

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

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

• QC ワークフロー全体を実行するか、特に plotFingerprint を使用します
• 結果の解釈方法を説明します
• 結果に基づいて次のアクションを提案します

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

• 2 段階の手順を案内します：computeMatrix → plotHeatmap
• 適切な行列モード（reference-point と scale-regions）の選択を支援します
• 可視化パラメーターとクラスタリングのオプションを提案します

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

• 2 サンプルの比較には bamCompare を推奨します
• 複数サンプルには multiBamSummary と plotCorrelation を提案します
• 正規化方法の選択を案内します

ドキュメントの参照

ユーザーが詳細情報を必要とする場合：

• ツールの詳細：references/tools_reference.md の該当セクションを案内します
• ワークフロー：分析パイプライン全体については references/workflows.md を使用します
• 正規化：方法の選択については references/normalization_methods.md を参照します
• ゲノムサイズ：references/effective_genome_sizes.md を参照します

対話の例

ユーザー：「ChIP-seq データを解析する必要があります」

応答の進め方：

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

ユーザー：「どの正規化を使えばよいですか？」

応答の進め方：

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

ユーザー：「TSS 周辺のヒートマップを作成してください」

応答の進め方：

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

主な注意事項

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

関連スキル

• pydeseq2：DESeq2 の Python 移植版である PyDESeq2 を使用して、バルク RNA-seq のカウントデータの差次的発現解析を実行します。
• gtars：ゲノム区間向けの Rust／Python／CLI ツールキットである Gtars を使った作業を調査・計画します：BED RegionSet の集合演算（reduce、setdiff、intersec…
• scanpy：標準的なシングルセル RNA-seq 解析パイプラインです。