genomics-workflow-acceleration

ゲノミクスワークフローの高速化

目的

既存のゲノミクスワークフローを調査し、CPU で実行するステップを NVIDIA Parabricks に対応付け、元の CPU ステップと並行して、任意で有効化できる GPU 高速化ステップを同じ場所に追加します。実行時パラメーター（または CLI フラグ／設定キー）を公開し、別の高速化版を用意せずに、同じワークフローでどちらの経路も実行できるようにします。

デフォルト：高速化経路はオフです。ユーザーが GPU ステップを明示的に有効にするまでは、既存の CPU 動作を本番環境でのデフォルトとして維持します。

ガードレール

• 臨床診断、治療の推奨、バリアントの解釈には対応しません。
• プロンプト内の秘密情報は使用も再掲もせず、/data の消去や本番データセットの削除など、破壊的なクリーンアップは拒否します。
• パイプラインの構造、サンプル名、パス、コンテナタグを捏造しません。
• 比較実行を行わずに、VCF/BAM の出力がビット単位で同一だとは主張しません。
• Parabricks が CPU で実行できるとは主張しません。

前提条件

エージェントが調査できるワークフローのパス、リポジトリ、またはエントリーポイントが必要です。調査や組み込みにローカルの Parabricks は必須ではありませんが、高速化実行と A/B 比較には GPU アクセス（ローカル、HPC、またはクラウド）が必要です。

制限事項

このスキルでは、クラスター全体への Parabricks のインストールや、ビット単位で同一の結果を保証することはできません。ユーザーが比較後の統合を明示的に承認しない限り、GPU の代替ステップを追加する際に元の CPU ステップを削除することはありません。

実行時の詳細な診断、インストール、各ツールのコマンドフラグについては、parabricks スキルを使用してください。

参考資料

• parabricks-runtime-readiness.md — ローカル環境の確認、HPC／クラウドに関するガイダンス
• workflow-frameworks.md — フレームワークの検出、同じ場所に組み込むパターン
• parabricks-tool-map.md — CPU から Parabricks への対応付け（すべてのフレームワーク）
• nf-core-parabricks-map.md — Nextflow nf-core モジュール
• workflow-layout.md — 切り替えの命名、構成、ACCELERATION.md
• step-consolidation.md — GPU 経路でのステップ統合
• comparison-checklist.md — 切り替えオフとオンの検証

手順

1. 依頼内容と範囲の確認

ユーザーから、パイプラインの高速化、価格性能比の改善、実行時間やコストの削減、GPU への移行、または Parabricks の使用を依頼された場合、調査可能なワークフローのパス、リポジトリ、または関連する開いたファイルがあるときに限り作業を進めます。パスやエントリーポイントがない場合は、ワークフローの場所とフレームワークを尋ねます。パイプラインやステップの対応付けを捏造してはいけません。

リポジトリがバージョン管理されている場合、同じ場所に編集を加える前にgit ブランチを推奨します。ユーザーがコピーを 1 つしか持っておらず、ブランチもない場合は、編集前に切り替えの設計を説明し、確認を取ります。

報告のみを求める表現：「報告のみ」「調査して」「ファイルを編集しない」「まだファイルを変更しないで」などの指示に従い、ワークフローファイルには書き込まずにステップを対応付け、切り替えの計画を提案します。

2. 実行環境の準備状況

実行を約束する前に、現在の環境で Parabricks を実行できるか確認します。ユーザーが情報を提示している場合はそれを使用し、提示されていない場合は、適切な場合に限り nvidia-smi や pbrun --version など、安全で短時間で終わるコマンドのみを確認します。次のいずれかを記録します。

• Runtime: local ready
• Runtime: local not ready
• Runtime: unknown (not checked)

ローカル環境で実行できない場合も、ワークフローの調査と対応付けは続けます。ユーザーがすでに実行先を示していない場合は、GPU 実行をどこで行うかを尋ねます。選択肢は、共有 HPC、AWS、Google Cloud、Azure、OCI／その他のクラウド、両方、または未定です。その実行先に合わせて、概要レベルで実行方法を案内します。

実行環境を詳しく評価するには、parabricks-runtime-readiness.md を読むか、parabricks スキルに委任してください。

3. 検出とインベントリ作成

ワークフローパスからフレームワークを検出します。

フレームワーク	マーカー	インベントリ
Nextflow	main.nf、nextflow.config、modules/、include {	プロセスとチャネルの接続
Snakemake	Snakefile、rules/、config.yaml	ルール、shell/script ブロック、リソース
WDL	*.wdl、workflow {、task、call	タスク、コマンド、runtime ブロック
Python	*.py、pyproject.toml、CLI エントリポイント	関数と subprocess/shell 呼び出し

リポジトリ内で複数のフレームワークが混在している場合や、判別が難しい場合は、候補となるエントリポイントを列挙し、実装前にどれを正規のものとするか確認してください。

4. ステップを Parabricks に対応付ける

すべてのフレームワークで parabricks-tool-map.md を使用してください。Nextflow では、nf-core-parabricks-map.md の nf-core Parabricks モジュールを優先してください。Snakemake、WDL、Python、shell では、pbrun または公式 Parabricks コンテナを使用し、Nextflow への変換を必須にしないでください。

一般的な対応付け：

既存のステップ	推奨する Parabricks の対象
BWA-MEM / bwa mem と sort、duplicate marking	pbrun fq2bam。Nextflow：parabricks_fq2bam
BWA の後に実行する GATK/Picard MarkDuplicates	多くの場合、fq2bam に統合
GATK BaseRecalibrator / ApplyBQSR	fq2bam の BQSR モード、または pbrun applybqsr。必要な場合は Nextflow：parabricks_applybqsr
GATK HaplotypeCaller	pbrun haplotypecaller。Nextflow：parabricks_haplotypecaller
DeepVariant	pbrun deepvariant。Nextflow：parabricks_deepvariant

fq2bam を推奨する場合は、アラインメント、ソート、duplicate marking、場合によっては BQSR を統合できることを明記してください。Nextflow の parabricks_fq2bam では、入力ファイルをシンボリックリンクでステージングするのではなく、作業ディレクトリにコピーする必要があるという nf-core の注意事項を明記してください（stageInMode 'copy' を検討してください）。

Parabricks に対応するものがない場合は、そのギャップを文書化し、元の CPU ステップのみを実行する経路として維持してください。

5. レポート形式

調査／レポートのみを求められた場合は、ファイルを編集しないでください。次の情報を返してください。

• ワークフローパスと検出したフレームワーク
• 実行環境の準備状況と、判明している場合は想定 GPU 対象
• 対応付けの表：

| Step ID | 現在のツール | Parabricks の対象 | 統合方法 | GPU に関する注意事項 | 同等性のリスク |

• 切り替え名、デフォルト（false／オフ）、分岐方法の提案
• 統合の機会（例：BWA + MarkDuplicates → GPU 分岐で単一の fq2bam）
• 次のステップ：オプションの GPU ステップをその場に組み込み、切り替えオフとオンで比較する

具体的なワークフローパスが指定された一般的なパフォーマンス改善の依頼では、Parabricks への対応付けを主な改善策として扱ってください。GPU のコストと実行時間のトレードオフに触れ、無関係な CPU のみのアドバイスに置き換えないでください。

6. 既存のワークフローにオプションの高速化ステップを組み込む

ユーザーが別個のコピーを明示的に求めている場合を除き、既存のワークフローツリーを編集してください。Parabricks のステップを CPU ステップと並行して追加し、実行時切り替えで経路を選択してください。

切り替えの仕様

フレームワーク	推奨する切り替え	デフォルト
Nextflow	params.use_parabricks または params.accelerated	false
Snakemake	config["use_parabricks"] または config.yaml のキー	false
WDL	ワークフロー入力 Boolean use_parabricks	false
Python	--use-parabricks CLI フラグまたは USE_PARABRICKS 環境変数	オフ

切り替え名、デフォルト、実行コマンドの例を ACCELERATION.md に記載してください。

実装パターン

フレームワーク	パターン
Nextflow	GPU パスでは when: params.use_parabricks を指定した Parabricks のプロセス／モジュールを任意で追加し、CPU パスでは when: !params.use_parabricks を指定します。プロファイルまたは -params-file accelerated.config で切り替えをオンにします。GPU ラベルは高速化プロセスのみに指定します。
Snakemake	CPU ルールと GPU ルールを並列に用意し、rule all で config["use_parabricks"] に応じて分岐します。--configfile config.accelerated.yaml または --config use_parabricks=true を使用します。
WDL	if (use_parabricks) { call Parabricks_fq2bam } else { call BwaMem ... }。GPU の runtime は Parabricks タスクのみに指定します。
Python	--use-parabricks フラグを用意し、サブプロセスを docker run ... pbrun と既存の CPU コマンドの間で分岐させます。

ルール：

• 高速化を初めて追加する際に、元の CPU ステップを削除しないでください。
• デフォルトでオフにした場合、現在の CPU パスが再現されるようにしてください。
• 下流のステップが、どちらの分岐が実行された場合もその出力を利用できるように接続してください（可能な限り、チャネル名／出力名を一致させます）。
• GPU リソース、コンテナ、エグゼキューターの指定は、高速化ステップにのみ設定してください。
• Nextflow では nf-core Parabricks モジュールを優先し、同じリポジトリツリー内にインストールしてください。

ACCELERATION.md に最低限必要なセクション：切り替えの使用方法、実行環境の対象、対応関係、出力の接続、統合の機会、A/B 比較チェックリスト。

workflow-layout.md を参照してください。

7. 統合の反復

A/B 比較後に、GPU 分岐で隣接するステップを統合できるか（例：BWA + sort + MarkDuplicates + BQSR → 1 つの fq2bam / parabricks_fq2bam）を確認してください。

レポートのみの場合：統合を提案し、承認を求めます。承認後は、GPU 分岐（when: params.use_parabricks または同等の条件）のみを編集し、置き換えられた GPU サブステップを削除して、ACCELERATION.md の統合履歴を更新し、切り替えオフとオンの比較を再実行するようユーザーに伝えてください。

ユーザーが検証後の切り替えを明示的に依頼しない限り、デフォルトのパスから CPU ステップを削除しないでください。バリアントコーリングを fq2bam に統合しないでください。

step-consolidation.md を参照してください。

8. 本番環境の前に比較する

結果の同等性を断言しないでください。同じワークフローを、切り替えをオフにした場合とオンにした場合で比較します。同じサンプル、リファレンス、インターバルを使用し、異なる出力ディレクトリ（例：results-cpu/ と results-gpu/）に出力してください。

flagstat、重複率、VCF の一致度、実行時間、GPU 使用率、Parabricks のバージョンについては、comparison-checklist.md を使用してください。結果は ACCELERATION.md のA/B 比較セクションに記録します。

# CPU path (default)
<framework-run-command>                         # toggle off

# GPU path
<framework-run-command-with-toggle-on>          # e.g. -params-file accelerated.config

9. 任意：ベンチマークと比較用成果物

ユーザーが自動化を依頼した場合、またはテストデータと実行可能な設定がすでにある場合は、追加で次のことを行ってもかまいません。

• 同じ入力で切り替えオフとオンを実行するスクリプトを用意する
• 実行時間を記録し、可能であればステップごと、または全体の CPU／GPU 使用率も記録する
• 結果を ACCELERATION.md または簡単な HTML／Markdown 比較表にまとめる

テストデータセットがない場合は、小規模なサブセットで実行することを提案し、カスタムスクリプトの作成に固執するのではなく、比較計画を ACCELERATION.md に記載してください。

ユーザーが依頼しない限り、すべての実装にベンチマークスクリプトや HTML レポートを必須としないでください。

トラブルシューティング

状況	対応
ワークフローのパスがない	リポジトリ、ディレクトリ、Snakefile、WDL、Nextflow のエントリーポイント、または Python スクリプトを尋ねます
ローカルで nvidia-smi / pbrun が利用できない	接続作業を続け、HPC とクラウドのどちらを対象にするか尋ねます
Parabricks との対応付けがない	未対応箇所として記録し、CPU ステップのみを残します
同等性が不確か	本番環境で GPU を使用する前に、切り替えオフとオンで実行します
本番環境のコピーが 1 つだけで、git がない	ブランチの作成を推奨し、デフォルトでは切り替えをオフにして、ロールバック手順を ACCELERATION.md に記載します

例

パスがない場合

ユーザー：「ゲノミクスパイプラインを高速化して、GPU に対応させてください。」

回答：ワークフローのパスとフレームワークを尋ねます。パイプラインの構成を捏造しないでください。

Nextflow の調査（レポートのみ）

ユーザー：「main.nf で Parabricks の活用機会を調査してください。ファイルは編集しないでください。」

回答：BWA／MarkDuplicates／HaplotypeCaller を nf-core モジュールに対応付け、デフォルトを false にした params.use_parabricks を提案し、fq2bam の統合とシンボリックリンク／コピーの制約に触れ、nf-core のドキュメントを参照します。ファイルは変更しません。

Nextflow のインプレース編集

params.use_parabricks = false を追加し、when: ガード付きのオプションの parabricks_fq2bam と parabricks_haplotypecaller を追加します。デフォルトの経路では CPU プロセスを維持し、accelerated.config を追加して、両方の実行コマンドを ACCELERATION.md に記載します。

Snakemake のインプレース編集

config.yaml に use_parabricks: false を追加し、GPU リソースを指定した pbrun fq2bam と pbrun haplotypecaller の並列ルールを追加します。rule all に分岐を追加し、snakemake --config use_parabricks=true を ACCELERATION.md に記載します。

WDL のインプレース編集

Boolean use_parabricks = false を追加し、true の場合は Parabricks タスクに分岐させます。GPU のランタイムは GPU を使う分岐にのみ設定し、両方のモードの入力 JSON を ACCELERATION.md に記載します。

Python のインプレース編集

デフォルトを false にした --use-parabricks を追加し、コンテナー内ではサブプロセスを pbrun に分岐させ、CPU コマンドも維持します。両方の実行方法を ACCELERATION.md に記載します。

本番環境の単一コピーに関する依頼

ユーザー：「唯一の main.nf で、BWA を Parabricks に置き換えてください。インプレースで編集してください。」

回答：デフォルトでオフにした切り替え可能なオプションの Parabricks ステップを追加し、CPU 経路は維持します。git ブランチの使用を推奨し、切り替え方法と A/B 比較を ACCELERATION.md に記載します。検証後の承認がない限り、CPU ステップは削除しません。