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 时返回该 ID。
6. 如果执行失败，报告首个失败点和下一步排查目标（.nextflow.log、pipeline_info、失败任务日志）。

所需输入

必需：

• 肿瘤 BAM 路径
• 正常样本 BAM 路径
• 患者 ID
• 肿瘤样本 ID
• 正常样本 ID
• 输出目录
• 必须且只能指定一种参考基因组模式：--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（如有检测到）。

Agent 回复规范

调用此技能后，每次回复都应包含：

• 使用的确切命令或生成的脚本路径
• 已运行验证检查的确认信息
• 运行类型（dry-run 或 run）
• 可用时提供调度器作业 ID
• 一个具体的后续验证／排查步骤

快速开始

试运行：

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

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，而不是猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一条染色体、几千个细胞）上运行流水线。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 在解释结果之前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并统一（liftover、ID mapping）后再继续。
已安装版本中缺少这些说明所提到的函数、标志或端点	查看已安装版本自带的文档（help()、--help、官方文档），调整后告知用户。切勿虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信原则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 解释生物学意义时，不得超出统计结果所支持的范围；报告多重检验校正。
• 请将此处与特定版本相关的细节视为可能已过时：务必根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征求同意。

相关技能

• nextflow：端到端构建、运行和调试 Nextflow 数据流水线及 nf-core 工作流。