pacsomatic

用途

pacsomatic 是一个面向 nf-core/pacsomatic 配对肿瘤-正常（matched tumor-normal）工作流的操作工具包，输入为 BAM 文件。它围绕单一辅助入口脚本提供可复现的执行工作流，覆盖校验、产物生成与可选执行。

主要入口：

scripts/run_pacsomatic.py

该辅助脚本负责：

校验必需的标识符、文件、参考模式与运行时前置条件
写出兼容 pacsomatic 的样本表（patient,sample,status,bam,pbi）
生成 params YAML 与启动脚本，以支持可复现的重跑
支持 dry-run 校验与 run/submit 执行路径

该技能被定位为 pacsomatic 操作的默认路径。除非用户明确要求手动构建命令，否则不应绕过它直接手工拼装 nextflow run nf-core/pacsomatic 命令。

何时使用

当用户提出以下需求时调用该技能：

从 BAM 文件运行配对肿瘤-正常分析
生成或修复 pacsomatic 样本表与启动产物
在本地执行或提交到调度器（LSF/Slurm/PBS/SGE）
在执行前进行 dry-run 校验
排查启动失败或汇总运行输出

不适用于：

超出运行级合理性检查的深层生物学解读
在未明确要求时编辑流程内部实现

典型触发语句：

"run nf-core/pacsomatic for this tumor-normal pair"
"prepare pacsomatic samplesheet and launch script"
"do a dry run first and tell me what is missing"
"submit pacsomatic to slurm/lsf and return the job id"
"why did pacsomatic submission fail"

路由与执行规则

始终先收集必需的运行输入。
始终通过 scripts/run_pacsomatic.py 进行校验与产物生成。
当用户仅要求检查/校验时，默认使用 --dry-run。
仅当用户要求执行/提交时使用 --run。
对于调度器模式，包含执行器特定的资源参数，并在可用时返回检测到的作业 ID。
如果执行失败，报告首个失败点与下一步排查目标（.nextflow.log、pipeline_info、失败任务日志）。

必需输入

必需：

tumor BAM 路径
normal BAM 路径
patient ID
tumor sample ID
normal sample ID
输出目录
恰好一种参考模式：--fasta 或 --genome

可选：

profile、资源、调度器 account/queue
流程版本（-r）
params 文件、resume/report/dag 标志
--dry-run 和/或 --run

工作流

校验身份与输入约束。
校验必需的本地路径（BAM、可选 PBI、可选 FASTA）。
解析运行时与依赖检查。
构建样本表与生成的 params YAML。
为所选执行器生成启动脚本。
如果为 --dry-run 且非 --run，在产物生成后停止。
如果为 --run，本地执行或提交到调度器。
返回命令/脚本路径、校验状态与作业 ID（如检测到）。

代理响应约定

每次调用后的响应应包含：

使用的确切命令或生成的脚本路径
确认校验检查已运行
运行类型（dry-run 与 run）
调度器作业 ID（如可用）
一个具体的下一步校验/排查步骤

快速开始

Dry run：

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）：

配置

使用 config.yaml 作为 profile/executor/runtime 默认值的基线。当用户需求不同时，在调用时覆盖。

测试

从技能根目录运行单元测试：

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

代理操作流程

检查环境。确认工具版本、参考基因组/注释构建与输入格式（FASTQ、BAM、VCF、h5ad）。
明确输入。从数据或用户处确认格式、标识符与参数。对任何会改变结果的取值，应询问而非猜测。
先运行小版本。先在小子集（一个样本、一条染色体、几千个细胞）上运行流程。
使用上述说明与参考执行完整任务。
校验结果。在解读结果前检查 QC 指标、样本身份、基因组构建一致性与批次效应。
报告。说明运行了什么（版本、命令、参数）、检查了什么、以及仍不确定的内容。

异常处理

输入之间的基因组构建或标识符不匹配：停止，并在继续前进行协调（liftover、ID 映射）。
这些说明中的函数、标志或端点在已安装版本中缺失：查阅已安装版本自身的文档（help()、--help、官方文档），适配并告知用户。绝不臆造 API。
必需的输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。

完整性规则

绝不捏造结果、参数、标识符、引用或统计。如果某事项无法运行或验证，应明确说明。
不超出统计支持范围解读生物学意义；报告多重检验校正。
将此处版本特定的细节视为可能过时：对照已安装版本的官方文档进行确认。
在涉及花钱、消耗共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前，先询问。

技能介绍

用途