pbmm2

Depending on your input data and requirements, use one of the following common patterns:

• Pre-indexing references: Index a reference once to reuse it for multiple alignments, which is faster.
• On-the-fly sorting: Align reads and sort the output in a single step using --sort.
• XML datasets: Align PacBio subreadsets or consensus readsets using .xml files.
• Streaming output: Omit the output file argument to stream BAM data to stdout for piping into other tools like samtools.
• CCS FASTQ input: Align CCS data from FASTQ files using the CCS preset.

# A. Generate index file for reference and reuse it to align reads
$ pbmm2 index ref.fasta ref.mmi --preset SUBREAD
$ pbmm2 align ref.mmi movie.subreads.bam ref.movie.bam --preset SUBREAD

# B. Align reads and sort on-the-fly, with 4 alignment and 2 sort threads
$ pbmm2 align ref.fasta movie.subreads.bam ref.movie.bam --preset SUBREAD --sort -j 4 -J 2

# C. Align reads, sort on-the-fly, and create PBI
$ pbmm2 align ref.fasta movie.subreadset.xml ref.movie.alignmentset.xml --preset SUBREAD --sort

# D. Omit output file and stream BAM output to stdout
$ pbmm2 align hg38.mmi movie1.subreadset.xml --preset SUBREAD | samtools sort > hg38.movie1.sorted.bam

# E. Align CCS fastq input and sort output
$ pbmm2 align ref.fasta movie.Q20.fastq ref.movie.bam --sort --rg '@RG\tID:myid\tSM:mysample'

By default, pbmm2 uses recommended parameter sets to simplify configuration. The available presets are:

• SUBREAD
• CCS or HIFI (default)
• ISOSEQ
• UNROLLED

Presets vary by version; check --help for details. You can override specific parameters from your chosen set using the following flags:

Alignment Parameters

• -k: k-mer size (max 28). Default: -1.
• -w: Minimizer window size. Default: -1.
• -u: Disable homopolymer-compressed k-mer (active for SUBREAD & UNROLLED).
• -A: Matching score. Default: -1.
• -B: Mismatch penalty. Default: -1.
• -z: Z-drop score. Default: -1.
• -Z: Z-drop inversion score. Default: -1.
• -r: Bandwidth for chaining and DP-based alignment. Default: -1.
• -g: Stop chain elongation if no minimizers in N bp. Default: -1.

Gap Penalty Overrides

For piece-wise linear gap penalties (where a k-long gap costs min{o+k*e,O+k*E}):

• -o, --gap-open-1: Gap open penalty 1. Default: -1.
• -O, --gap-open-2: Gap open penalty 2. Default: -1.
• -e, --gap-extend-1: Gap extension penalty 1. Default: -1.
• -E, --gap-extend-2: Gap extension penalty 2. Default: -1.
• -L, --lj-min-ratio: Long join flank ratio. Default: -1.

ISOSEQ Specific Overrides

• -G: Max intron length (affects -r). Default: -1.
• -C: Cost for non-canonical GT-AG splicing. Default: -1.
• --no-splice-flank: Do not prefer splice flanks GT-AG.

The pbmm2 executable provides two primary subcommands for genomic data processing: index and align.

Subcommands

• index: Used to generate an index file from a reference genome (e.g., FASTA) for faster subsequent alignments.
• align: Used to align sequencing reads (BAM, XML, or FASTQ) against a reference genome or a pre-computed index.

Typical Workflows

1. Index then Align (Recommended for reuse): Generate an .mmi index file first, then use it for alignment to save time on multiple runs.

$ pbmm2 index ref.fasta ref.mmi
$ pbmm2 align ref.mmi movie.subreads.bam ref.movie.bam

2. Direct Alignment (On-the-fly): Align directly against a FASTA file. You can use the --sort flag to sort the output BAM on-the-fly.

$ pbmm2 align ref.fasta movie.subreads.bam ref.movie.bam --sort -j 4 -J 2

Note: -j specifies alignment threads and -J specifies sort threads.

3. Align CCS FASTQ input: Use the --preset CCS flag when aligning CCS (Circular Consensus Sequencing) FASTQ files.

$ pbmm2 align ref.fasta movie.Q20.fastq ref.movie.bam --preset CCS --sort --rg '@RG\tID:myid\tSM:mysample'

4. Stream output to stdout: Omit the output file argument to pipe the BAM output to another tool like samtools.

$ pbmm2 align hg38.mmi movie1.subreadset.xml | samtools sort > hg38.movie1.sorted.bam

# Example: Indexing a reference
$ pbmm2 index ref.fasta ref.mmi

# Example: Aligning reads using the index
$ pbmm2 align ref.mmi movie.subreads.bam ref.movie.bam