pacsomatic

pacsomatic

概要

このスキルは、検証、成果物の生成、必要に応じた実行を処理する単一のヘルパーエントリーポイントを中心に、再現可能な nf-core/pacsomatic の実行ワークフローを提供します。

主なエントリーポイント：

• scripts/run_pacsomatic.py

ヘルパースクリプトは次の処理を行います。

• 必須の識別子、ファイル、リファレンスモード、実行時の前提条件を検証します
• pacsomatic 対応のサンプルシート（patient,sample,status,bam,pbi）を作成します
• 再現可能な再実行に使用する params YAML と起動スクリプトを生成します
• ドライラン検証と、実行／送信の処理経路に対応します

pacsomatic の操作には、このスキルを標準の方法として使用してください。ユーザーから手動でのコマンド作成を明示的に依頼されない限り、手作業で組み立てた nextflow run nf-core/pacsomatic コマンドを使って、この方法を迂回しないでください。

このスキルを使用する場面

次の依頼があった場合に、このスキルを呼び出してください。

• BAM ファイルから腫瘍・正常ペアの解析を実行する
• pacsomatic のサンプルシートや起動用成果物を生成または修正する
• ローカルで実行する、またはスケジューラー（LSF/Slurm/PBS/SGE）に送信する
• 実行前にドライラン検証を行う
• 起動の失敗をトラブルシューティングする、または実行出力を要約する

次の用途には、このスキルを使用しないでください。

• 実行レベルの健全性チェックを超える、詳細な生物学的解釈
• 明示的に依頼されない限り、パイプライン内部を編集する

典型的な起動フレーズ：

• 「この腫瘍・正常ペアに対して nf-core/pacsomatic を実行して」
• 「pacsomatic のサンプルシートと起動スクリプトを準備して」
• 「まずドライランを行い、不足しているものを教えて」
• 「pacsomatic を slurm/lsf に送信して、ジョブ ID を返して」
• 「pacsomatic の送信が失敗した理由を教えて」

ルーティングと実行のルール

1. 必ず最初に、実行に必要な入力をすべて収集します。
2. 検証と成果物の生成には、必ず scripts/run_pacsomatic.py を使用します。
3. ユーザーが確認／検証のみを求めている場合は、デフォルトで --dry-run を使用します。
4. --run は、ユーザーが実行／送信を求めている場合にのみ使用します。
5. スケジューラーモードでは、エグゼキューター固有のリソース引数を指定し、検出できた場合はジョブ ID を返します。
6. 実行に失敗した場合は、最初の失敗箇所と次に調査すべき対象（.nextflow.log、pipeline_info、失敗したタスクのログ）を報告します。

必要な入力

必須：

• 腫瘍 BAM パス
• 正常 BAM パス
• 患者 ID
• 腫瘍サンプル ID
• 正常サンプル ID
• 出力ディレクトリ
• リファレンスモードを 1 つだけ指定：--fasta または --genome

任意：

• プロファイル、リソース、スケジューラーのアカウント／キュー
• パイプラインのバージョン（-r）
• params ファイル、resume/report/dag フラグ
• --dry-run および／または --run

ワークフロー

1. 識別情報と入力制約を検証します。
2. 必須のローカルパス（BAM、任意の PBI、任意の FASTA）を検証します。
3. 実行環境と依存関係のチェックを解決します。
4. サンプルシートと生成用 params YAML を作成します。
5. 選択したエグゼキューター用の起動スクリプトを生成します。
6. --dry-run が指定され、--run が指定されていない場合は、成果物の生成後に停止します。
7. --run が指定されている場合は、ローカルで実行するか、スケジューラーに送信します。
8. コマンド／スクリプトのパス、検証ステータス、検出された場合はジョブ ID を返します。

エージェント応答の要件

呼び出し後のすべての応答に、次の内容を含めてください。

• 実際に使用したコマンド、または生成したスクリプトのパス
• 検証チェックを実行したことの確認
• 実行タイプ（dry-run または run）
• 利用可能な場合は、スケジューラーのジョブ ID
• 検証／トリアージのための具体的な次の手順を 1 つ

クイックスタート

ドライラン：

python scripts/run_pacsomatic.py \
  --tumor-bam /path/to/tumor.bam \
  --normal-bam /path/to/normal.bam \
  --patient-id P001 \
  --tumor-sample-id P001_T \
  --normal-sample-id P001_N \
  --outdir /path/to/output \
  --genome GRCh38 \
  --profile singularity,sanger \
  --dry-run

スケジューラーでの実行例（Slurm）：

python scripts/run_pacsomatic.py \
  --tumor-bam /path/to/tumor.bam \
  --normal-bam /path/to/normal.bam \
  --patient-id P001 \
  --tumor-sample-id P001_T \
  --normal-sample-id P001_N \
  --outdir /path/to/output \
  --genome GRCh38 \
  --profile singularity,sanger \
  --executor slurm \
  --queue compute \
  --project my_account \
  --cpus 16 \
  --memory-gb 64 \
  --walltime 48:00 \
  --run

設定

プロファイル／エグゼキューター／実行環境のデフォルト設定には、config.yaml を基準として使用します。ユーザーの要件と異なる場合は、呼び出し時に上書きします。

テスト

スキルのルートディレクトリから単体テストを実行します。

python -m unittest discover -s tests/pacsomatic -v

参考資料

• references/agent-playbook.md
• references/config-and-output.md
• references/pacsomatic_guide.md
• scripts/run_pacsomatic.py

エージェントの運用手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 まず少数のサブセット（1 サンプル、1 染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの同一性、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、まだ不確かな点を明記します。

このような場合	次の対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に処理を中止し、整合させます（liftover、ID マッピング）。
この手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して調整し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• 統計的な根拠を超えて生物学的な意義を解釈しないでください。多重検定補正を報告してください。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドクォータを消費する操作、個人データや患者データを扱う操作、取り消せない操作を行う前に、必ず確認してください。

関連スキル

• nextflow：Nextflow データパイプラインおよび nf-core ワークフローを、構築、実行、デバッグまで一貫して行います。