skills/parabricks/references/pbrun-applybqsr.md

# Parabricks applybqsr

Use this reference for NVIDIA Parabricks `pbrun applybqsr` — applying a BQSR recalibration report to aligned BAM/CRAM reads.

## First Steps

1. Confirm the Parabricks version or container tag.
2. Confirm the user already has a BQSR recalibration report. If not, route to
   `pbrun-bqsr.md`.
3. Collect required inputs:
   - Reference FASTA path.
   - Input BAM or CRAM path.
   - Input recalibration report path.
   - Output BAM or CRAM path.
4. Ask about optional interval files, temporary directory, logs, and GPU count
   only when relevant.
5. For runtime readiness or installation questions, use
   `runtime-environment.md`.

## Command Shape

```bash
docker run --rm --gpus all \
  --volume /host/input:/workdir \
  --volume /host/output:/outputdir \
  --workdir /workdir \
  nvcr.io/nvidia/clara/clara-parabricks:<version> \
  pbrun applybqsr \
  --ref /workdir/<reference.fa> \
  --in-bam /workdir/<input.bam> \
  --in-recal-file /workdir/<input.recal.txt> \
  --out-bam /outputdir/<recalibrated.bam>
```

Verify option names against the tool reference for the selected version before
finalizing interval, threading, logging, or temporary-directory flags.

## ApplyBQSR Option Mapping

Use this mapping when translating a GATK `ApplyBQSR` command to
`pbrun applybqsr`. Parabricks v4.7.0 documents `applybqsr` as the GPU
counterpart for applying a GATK BQSR report, but the CLI is not one-to-one:
GATK long names are often shortened, and Parabricks exposes Docker/GPU runtime
controls that GATK does not have.

| GATK option | `pbrun applybqsr` equivalent | Notes |
| --- | --- | --- |
| `--reference`, `-R` | `--ref` | Required reference FASTA path. |
| `--input`, `-I` | `--in-bam` | Required BAM/CRAM input path. |
| `--bqsr-recal-file` | `--in-recal-file` | Required recalibration report generated by `pbrun bqsr` or GATK `BaseRecalibrator`. |
| `--output`, `-O` | `--out-bam` | Required output BAM/CRAM path. |
| `--intervals`, `-L` | `--interval` or `--interval-file` | Parabricks separates inline intervals from interval files. |
| `--interval-padding`, `-ip` | `--interval-padding`, `-ip` | Same padding role. |
| `--tmp-dir` / `--TMP_DIR` | `--tmp-dir` | Same temporary-directory role, but Parabricks treats it as a wrapper/runtime path. |
| `--verbosity` / `--VERBOSITY` | `--verbose` | Partial equivalent only: Parabricks exposes a boolean verbose flag, not a log-level enum. |
| `--version` | `--version` | Same version-reporting role. |
| `--java-options` | No direct equivalent | Java heap/runtime settings do not apply to the Parabricks containerized GPU tool. |
| `--arguments_file` | No direct equivalent | GATK argument-file expansion is not documented for `pbrun applybqsr`. |
| `--read-index`, `--read-validation-stringency`, common GATK engine flags | No direct equivalent | GATK engine-specific controls are not exposed by current Parabricks docs. |

If a GATK `ApplyBQSR` option is not listed above, assume there is no direct
`pbrun applybqsr` flag until the selected Parabricks version's tool reference
says otherwise.

## applybqsr Options Without ApplyBQSR Equivalents

| `pbrun applybqsr` option | Why it has no GATK ApplyBQSR equivalent |
| --- | --- |
| `--num-threads` | Parabricks worker-thread count. |
| `--num-gpus` | Parabricks GPU count. |
| `--logfile` | Parabricks wrapper log file path. |
| `--x3` | Parabricks option to show full command-line arguments. |
| `--with-petagene-dir` | Parabricks/PetaGene integration. |
| `--keep-tmp` | Parabricks temporary-file retention. |
| `--no-seccomp-override` | Parabricks Docker/seccomp behavior. |
| `--preserve-file-symlinks` | Parabricks path handling behavior. |

## Validation

- Reference, BAM/CRAM, and recalibration report paths resolve inside the
  container.
- Output BAM/CRAM is created in the mounted output directory.
- Logs do not show reference mismatch, missing recalibration report, interval,
  Docker mount, CUDA, or out-of-memory errors.
- The output is used downstream instead of the original unrecalibrated input.

## Guardrails

- Do not generate a recalibration report here; use `bqsr` for that step.
- Do not apply a recalibration report from a different reference/sample unless
  the user explicitly confirms compatibility.
- Do not invent intervals, output names, or runtime estimates.

## Key References

- <https://docs.nvidia.com/clara/parabricks/latest/documentation/tooldocs/man_applybqsr.html>