skills/parabricks/references/pbrun-minimap2.md

# Parabricks minimap2

Use this reference for NVIDIA Parabricks `pbrun minimap2` — GPU-accelerated long-read FASTQ-to-BAM/CRAM alignment via minimap2.

## First Steps

1. Confirm the Parabricks version or container tag.
2. Confirm the sequencing technology and use case:
   - Oxford Nanopore.
   - PacBio HiFi or CLR.
   - Splice-aware long-read RNA alignment if supported by the selected version.
3. Collect required inputs:
   - Reference FASTA path or minimap2 index path.
   - Input FASTQ or BAM/CRAM path.
   - Output BAM or CRAM path.
4. Ask about presets, known-sites, interval files, read groups, and temporary
   directory only when relevant and supported.
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 minimap2 \
  --ref /workdir/<reference.fa> \
  --in-fq /workdir/<long_reads.fastq.gz> \
  --out-bam /outputdir/<aligned.bam>
```

Verify exact preset, index, BAM/CRAM input, known-sites, and output options
against the selected version before finalizing.

## minimap2/GATK Option Mapping

Use this mapping when translating a baseline minimap2 plus GATK/Picard
post-processing workflow to `pbrun minimap2`. Parabricks v4.7.0 documents
`minimap2` as a GPU long-read alignment workflow that can sort, mark
duplicates, and optionally run BQSR, so the CLI maps to several upstream
commands rather than one single tool.

| Baseline option | `pbrun minimap2` equivalent | Notes |
| --- | --- | --- |
| `minimap2 <reference>` | `--ref` | Required reference FASTA path. |
| minimap2 index input | `--index` | Optional minimizer index generated by vanilla minimap2. |
| minimap2 FASTQ query input | `--in-fq` | Repeatable FASTQ/FASTQ.GZ input. |
| BAM/CRAM input for preprocessing workflow | `--in-bam` | Parabricks input BAM/CRAM mode. |
| `minimap2 -x` | `--preset` | Parabricks supports documented presets such as `map-pbmm2`, `map-hifi`, `map-ont`, `lr:hq`, `splice`, `splice:hq`, and `splice:sr`. |
| `minimap2 -t` | `--num-threads` | Processing thread count. |
| `minimap2 -k` | `--minimizer-kmer-len`, `-k` | Minimizer k-mer length. |
| `minimap2 -uf` | `--forward-transcript-strand`, `-uf` | Splice preset strand control. |
| `minimap2 -ub` | `--both-strands`, `-ub` | Splice preset strand control. |
| minimap2 splice junction BED options | `--jump-bed`, `-j`; `--junc-bed` | Parabricks splice annotation inputs. |
| `minimap2 --MD` / `--md` | `--md` | Output MD tag. |
| `minimap2 --eqx` | `--eqx` | Write `=/X` CIGAR operators. |
| `minimap2 -y` | `--copy-comment`, `-y` | Append FASTQ comment to BAM output. |
| `minimap2 -R` | `--read-group-*` flags | Parabricks builds read group fields from explicit tags rather than accepting the raw minimap2 string. |
| `minimap2 -a` SAM output piped to sorting | `--out-bam` | Parabricks writes sorted BAM/CRAM output. |
| GATK/Picard `MarkDuplicates -M` | `--out-duplicate-metrics` | Duplicate metrics output after marking duplicates when applicable. |
| GATK `BaseRecalibrator --known-sites` | `--knownSites` | Repeatable known-sites VCF input. |
| GATK `BaseRecalibrator --output` | `--out-recal-file` | BQSR report output. |
| GATK `BaseRecalibrator --intervals`, `-L` | `--interval`, `--interval-file` | Parabricks separates inline intervals from interval files. |
| GATK `BaseRecalibrator --interval-padding`, `-ip` | `--interval-padding`, `-ip` | Same padding role. |
| GATK/Picard `--TMP_DIR` | `--tmp-dir` | Same temporary-directory role, but Parabricks treats it as a wrapper/runtime path. |
| GATK/Picard `--VERBOSITY` | `--verbose` | Partial equivalent only: Parabricks exposes a boolean verbose flag. |
| GATK/Picard `--version` | `--version` | Same version-reporting role. |
| GATK/Picard `--java-options` | No direct equivalent | Java runtime settings do not apply to the Parabricks containerized GPU pipeline. |
| Upstream minimap2 options not listed here | No direct equivalent | Not exposed by current Parabricks docs for `pbrun minimap2`. |

If a minimap2, SortSam, MarkDuplicates, or BaseRecalibrator option is not
listed above, assume there is no direct `pbrun minimap2` flag until the
selected Parabricks version's tool reference says otherwise.

## minimap2 Options Without minimap2/GATK Equivalents

| `pbrun minimap2` option | Why it has no direct baseline equivalent |
| --- | --- |
| `--pbmm2`, `--pbmm2-unmapped` | Parabricks compatibility mode for pbmm2-style output and unmapped records. |
| `--out-qc-metrics-dir` | Parabricks workflow output for QC metrics. |
| `--standalone-bqsr` | Parabricks mode control for running BQSR after sorted BAM generation. |
| `--nstreams`, `--max-queue-chunks`, `--max-queue-reads`, `--chunk-size` | Parabricks GPU/CPU pipeline queue and chunk controls. |
| `--gpuwrite`, `--gpuwrite-deflate-algo`, `--gpusort`, `--use-gds` | GPU-accelerated write/sort/storage controls. |
| `--low-memory` | Parabricks memory-reduction mode. |
| `--logfile`, `--x3` | Parabricks wrapper logging and full-argument display. |
| `--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. |
| `--num-gpus` | Parabricks GPU count. |

## Validation

- Reference or index and input read paths resolve inside the container.
- Output BAM/CRAM is created.
- Selected preset matches sequencing technology and analysis goal.
- Logs do not show reference/index, preset, mount, CUDA, or out-of-memory
  errors.

## Guardrails

- Do not use `minimap2` for ordinary short-read BWA-MEM alignment; route to
  `pbrun-fq2bam.md`.
- Do not infer ONT/PacBio presets from filename alone.
- Do not claim variant-calling completion; this skill only covers alignment and
  related preprocessing available in `minimap2`.

## Key References

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