Version Compatibility
Reference examples tested with: minimap2 2.26+, samtools 1.19+
Before using code patterns, verify installed versions match. If versions differ:
- CLI:
<tool> --version then <tool> --help to confirm flags
If code throws ImportError, AttributeError, or TypeError, introspect the installed
package and adapt the example to match the actual API rather than retrying.
Long-Read Alignment with minimap2
"Align my long reads to the reference" → Map ONT or PacBio reads using minimap2 with technology-specific presets for optimal sensitivity and accuracy.
- CLI:
minimap2 -ax map-ont ref.fa reads.fq | samtools sort -o aligned.bam (ONT), minimap2 -ax map-hifi (PacBio HiFi)
Oxford Nanopore Alignment
# Basic ONT alignment
minimap2 -ax map-ont reference.fa reads.fastq.gz | \
samtools sort -o aligned.bam
samtools index aligned.bam
PacBio HiFi Alignment
# PacBio HiFi reads (high accuracy)
minimap2 -ax map-hifi reference.fa reads.fastq.gz | \
samtools sort -o aligned.bam
samtools index aligned.bam
PacBio CLR Alignment
# PacBio CLR (continuous long reads, lower accuracy)
minimap2 -ax map-pb reference.fa reads.fastq.gz | \
samtools sort -o aligned.bam
samtools index aligned.bam
Pre-Build Index for Multiple Runs
# Build index once
minimap2 -d reference.mmi reference.fa
# Use index for alignment
minimap2 -ax map-ont reference.mmi reads.fastq.gz | samtools sort -o aligned.bam
Common Options
minimap2 -ax map-ont \
-t 8 \ # Threads
-R '@RG\tID:sample\tSM:sample' \ # Read group
--secondary=no \ # No secondary alignments
--MD \ # Generate MD tag for variants
-Y \ # Use soft clipping for supplementary
reference.fa reads.fastq.gz | \
samtools sort -@ 4 -o aligned.bam
Splice-Aware Alignment (RNA)
# For direct RNA or cDNA sequencing
minimap2 -ax splice reference.fa reads.fastq.gz | \
samtools sort -o aligned.bam
With Junction BED (Known Splice Sites)
# Provide known splice junctions
minimap2 -ax splice --junc-bed junctions.bed \
reference.fa reads.fastq.gz | samtools sort -o aligned.bam
Assembly to Reference Alignment
# Assembly with ~0.1% divergence
minimap2 -ax asm5 reference.fa assembly.fa > aligned.sam
# Assembly with higher divergence (~5%)
minimap2 -ax asm20 reference.fa assembly.fa > aligned.sam
Output PAF (Faster, No BAM)
# PAF format (faster, for quick analysis)
minimap2 -x map-ont reference.fa reads.fastq.gz > alignments.paf
Keep Secondary and Supplementary
# Keep all alignments (for SV calling)
minimap2 -ax map-ont \
--secondary=yes \
-N 5 \ # Max secondary alignments
reference.fa reads.fastq.gz | samtools sort -o aligned.bam
Filter Alignments
# During alignment pipeline
minimap2 -ax map-ont reference.fa reads.fastq.gz | \
samtools view -b -q 10 | \ # Min mapping quality 10
samtools sort -o aligned.bam
Multiple FASTQ Files
# Concatenate inputs
minimap2 -ax map-ont reference.fa reads1.fastq.gz reads2.fastq.gz | \
samtools sort -o aligned.bam
# Or use file list
cat file_list.txt | xargs minimap2 -ax map-ont reference.fa | \
samtools sort -o aligned.bam
Output Statistics
# Get alignment statistics
samtools flagstat aligned.bam
# Detailed stats
samtools stats aligned.bam | grep ^SN
Convert PAF to BED
# Extract alignments to BED
awk 'OFS="\t" {print $6, $8, $9, $1, $12, ($5=="+")?"+":"-"}' alignments.paf > alignments.bed
Key Presets
| Preset | Description | Best For |
|---|
| map-ont | ONT reads | Nanopore genomic |
| map-hifi | PacBio HiFi | PacBio genomic |
| map-pb | PacBio CLR | PacBio CLR |
| splice | Long RNA reads | cDNA, direct RNA |
| asm5 | Low divergence | Same species assembly |
| asm20 | High divergence | Cross-species assembly |
| sr | Short reads | Illumina (basic) |
Key Parameters
| Parameter | Default | Description |
|---|
| -t | 3 | CPU threads |
| -k | 15 | K-mer size |
| -w | 10 | Minimizer window |
| -a | off | Output SAM |
| -x | none | Preset |
| --secondary | yes | Output secondary |
| -N | 5 | Max secondary alignments |
| --MD | off | Generate MD tag |
| -R | none | Read group header |
| -Y | off | Soft clipping for supplementary |
Output Formats
| Format | Flag | Description |
|---|
| PAF | (default) | Pairwise Alignment Format |
| SAM | -a | Sequence Alignment Map |
| BAM | -a | samtools | Binary SAM |
Related Skills
- medaka-polishing - Polish consensus with medaka
- structural-variants - Call SVs from alignments
- alignment-files/sam-bam-basics - BAM manipulation