# Pacsomatic Guide

This guide summarizes the official nf-core/pacsomatic usage and how this skill
helps an agent validate, prepare, and launch runs across compute platforms.

## What nf-core/pacsomatic runs

nf-core/pacsomatic is a Nextflow pipeline for matched tumor/normal PacBio HiFi
somatic analysis.

Typical upstream command from official docs:

```bash
nextflow run nf-core/pacsomatic \
  -profile <docker/singularity/.../institute> \
  --input samplesheet.csv \
  --outdir <OUTDIR> \
  --genome GRCh38
```

Important notes from docs:

- Input is a CSV samplesheet with columns: `patient,sample,status,bam[,pbi]`.
- `status` uses `1` for tumor and `0` for normal.
- Pipeline parameters should be passed via CLI flags or `-params-file`, not `-c`.

## Cross-agent reuse

This skill can be reused by other agents in the same workspace.

- Keep the whole folder `.github/skills/pacsomatic` intact when reusing.
- Other agents can either:
  - call `scripts/run_pacsomatic.py` to generate a backend-aware launch script, or
  - emit a direct platform-native script and return the matching launcher command.
- If moving to another repository, copy the same folder structure and keep
  `SKILL.md`, `references/`, and `scripts/` together.
- Validate environment assumptions per cluster (Nextflow module version,
  profile such as `singularity,sanger`, queue/project names, and network access
  for remote BAM URLs).

## Minimal samplesheet format

```csv
patient,sample,status,bam,pbi
ID1,ID1_tumor,1,/path/ID1_tumor.bam,/path/ID1_tumor.bam.pbi
ID1,ID1_normal,0,/path/ID1_normal.bam,/path/ID1_normal.bam.pbi
```

`pbi` is optional. If not available, leave it blank.

## Platform-aware execution model in this skill

By default, the helper generates artifacts. With `--run`, it executes/submits
using the selected `--executor` backend.

It produces:

- A validated samplesheet CSV from tumor/normal BAM inputs
- A standalone launch script that runs Nextflow + nf-core/pacsomatic
- A ready run command (for example `bash`, `bsub`, `sbatch`, `qsub`)
- Launcher output and detected job ID when `--run` is enabled

## Example: generate script only

```bash
python .github/skills/pacsomatic/scripts/run_pacsomatic.py \
  --tumor-bam /data/P1_tumor.bam \
  --normal-bam /data/P1_normal.bam \
  --patient-id P1 \
  --tumor-sample-id P1_tumor \
  --normal-sample-id P1_normal \
  --fasta /refs/GRCh38.fa \
  --outdir /results/p1 \
  --profile singularity \
  --executor local \
  --queue normal \
  --cpus 16 \
  --memory-gb 64 \
  --walltime 48:00
```

## Example: dry-run validation

```bash
python .github/skills/pacsomatic/scripts/run_pacsomatic.py \
  --tumor-bam /data/P1_tumor.bam \
  --normal-bam /data/P1_normal.bam \
  --patient-id P1 \
  --tumor-sample-id P1_tumor \
  --normal-sample-id P1_normal \
  --genome GRCh38 \
  --outdir /results/p1 \
  --profile singularity \
  --executor local \
  --dry-run
```

## Example: generate and submit immediately

```bash
python .github/skills/pacsomatic/scripts/run_pacsomatic.py \
  --tumor-bam /data/P1_tumor.bam \
  --normal-bam /data/P1_normal.bam \
  --patient-id P1 \
  --tumor-sample-id P1_tumor \
  --normal-sample-id P1_normal \
  --genome GRCh38 \
  --outdir /results/p1 \
  --profile singularity \
  --executor lsf \
  --run
```

## Example: submit on Slurm

```bash
python .github/skills/pacsomatic/scripts/run_pacsomatic.py \
  --tumor-bam /data/P1_tumor.bam \
  --normal-bam /data/P1_normal.bam \
  --patient-id P1 \
  --tumor-sample-id P1_tumor \
  --normal-sample-id P1_normal \
  --genome GRCh38 \
  --outdir /results/p1 \
  --profile singularity \
  --executor slurm \
  --queue compute \
  --cpus 16 \
  --memory-gb 64 \
  --run
```

## Direct command-line operation (no agent wrapper)

The helper is a standalone CLI and can be run directly from shell scripts,
terminal sessions, CI jobs, or workflow launch wrappers.

Supported HPC schedulers via `--executor`:

- `lsf` (uses `bsub`)
- `slurm` (uses `sbatch`)
- `pbs` (uses `qsub`)
- `sge` (uses `qsub`)

Local direct execution is also supported with:

- `--executor local` (runs generated script with `bash`)

## Direct LSF script (no Python wrapper)

If users request a ready-to-submit LSF script directly, provide a `.lsf.sh`
file that can be submitted as-is.

Example file: `submit_pacsomatic_hg008.lsf.sh`

```bash
#!/usr/bin/env bash
#BSUB -J Somatic_singularity
#BSUB -P Somatic_singularity
#BSUB -q heavy_io
#BSUB -n 16
#BSUB -M 64000
#BSUB -W 48:00
#BSUB -o out%J.out
#BSUB -e err%J.err

set -euo pipefail

RUN_DIR="${RUN_DIR:-$PWD/pacsomatic_hg008_run}"
OUTDIR="${OUTDIR:-$RUN_DIR/results}"
WORKDIR="${WORKDIR:-$RUN_DIR/work}"
SAMPLESHEET="$RUN_DIR/samplesheet.csv"

mkdir -p "$RUN_DIR" "$OUTDIR" "$WORKDIR"

cat > "$SAMPLESHEET" << 'CSV'
patient,sample,status,bam,pbi
Patient_HG008,DS_MT_T,1,https://raw.githubusercontent.com/nf-core/test-datasets/pacsomatic/testdata/HG008_Downsample_MT_tumor.bam,
Patient_HG008,DS_MT_N,0,https://raw.githubusercontent.com/nf-core/test-datasets/pacsomatic/testdata/HG008_Downsample_MT_normal.bam,
CSV

module load nextflow/21.10.5
export NXF_WORK="$WORKDIR"

nextflow run nf-core/pacsomatic \
  -profile singularity,sanger \
  --input "$SAMPLESHEET" \
  --outdir "$OUTDIR" \
  --genome GRCh38 \
  -with-report "$OUTDIR/HiFi_Somatic_Nextflow_Run_Report.html" \
  -with-dag "$OUTDIR/HiFi_Somatic_Flowchart.png" \
  -resume
```

Submit with:

```bash
bsub < submit_pacsomatic_hg008.lsf.sh
```

## LSF examples aligned with your cluster style

The script supports your style of submission, including `-P`, queue switching,
`module load nextflow/21.10.5`, `-resume`, and report/DAG outputs.

Built-in defaults now match your common combo:

- project: `Somatic_singularity`
- queue: `heavy_io`
- module-load: `module load nextflow/21.10.5`

Default LSF output naming now follows your style:

- stdout: `out%J.out`
- stderr: `err%J.err`

You can override with `--stdout-file` and `--stderr-file`, and optionally set
`--logdir` to place them under a specific directory.

```bash
python .github/skills/pacsomatic/scripts/run_pacsomatic.py \
  --tumor-bam /data/P1_tumor.bam \
  --normal-bam /data/P1_normal.bam \
  --patient-id P1 \
  --tumor-sample-id P1_tumor \
  --normal-sample-id P1_normal \
  --genome GRCh38 \
  --outdir /results/p1 \
  --project Somatic_test \
  --queue heavy_io \
  --memory-gb 20 \
  --job-name Somatic_test \
  --module-load "module load nextflow/21.10.5" \
  --with-report HiFi_Somatic_Nextflow_Run_Report.html \
  --with-dag HiFi_Somatic_Flowchart.png
```

For your Sanger configs usage, set combined profiles such as:

```bash
--profile singularity,sanger
```

Reference: <https://nf-co.re/configs/sanger/>

## Best practices

- Ensure BAMs are coordinate-valid and index files are available when possible.
- Use explicit pipeline version with `--pipeline-version` for reproducibility.
- Prefer pinning `--pipeline-version` when using fixed test datasets to avoid schema drift across pipeline revisions.
- Use `--params-file` for large parameter sets and keep script options minimal.
- Prefer containerized profile (`singularity` or `docker`) on HPC.
- Set `NXF_OPTS` memory ceiling if Nextflow launcher memory spikes.
- nf-core/pacsomatic may require a newer Nextflow than legacy module versions; if the cluster allows, prefer a modern Nextflow release compatible with the pipeline.