/bwa-mem2-dna-aligner

name: "bwa-mem2-dna-aligner"
description: "Fast short-read DNA aligner for WGS/WES/ChIP-seq. 2× faster BWA-MEM successor; outputs SAM/BAM with read group headers for GATK. Primary plus supplementary records for chimeric reads. Use STAR for RNA-seq splice-aware alignment; Bowtie2 is a comparable alternative."
license: "MIT"

BWA-MEM2 — DNA Short-Read Aligner

Overview

BWA-MEM2 aligns short DNA reads (Illumina, 50–250 bp) to a reference genome using the BWT-FM index. It is the standard aligner for whole-genome sequencing (WGS), whole-exome sequencing (WES), ChIP-seq, and ATAC-seq DNA alignment. BWA-MEM2 is 2× faster than the original BWA-MEM while producing identical results. It outputs SAM format with proper read group (`@RG`) headers required by GATK HaplotypeCaller and Picard tools. For paired-end reads, it marks proper pairs and resolves chimeric/split reads into supplementary alignments.

When to Use

• Aligning WGS or WES Illumina reads to a reference genome for variant calling (SNP, indel, SV)
• ChIP-seq or ATAC-seq DNA alignment to produce BAM files for peak calling with MACS3
• Producing GATK-compatible BAM files with `@RG` read group tags
• Aligning reads ≥ 50 bp; for shorter reads (< 50 bp), BWA-backtrack may be more appropriate
• Re-aligning legacy FASTQ files to an updated reference genome assembly
• Use **STAR** instead for RNA-seq reads that span splice junctions
• Use **Bowtie2** as an alternative for local alignment or when index size must be minimized

Prerequisites

• **Software**: bwa-mem2 (conda or pre-compiled binary), samtools
• **Reference**: genome FASTA (e.g., GRCh38, hg19, mm10)
• **RAM**: ~28 GB for human genome index; 6–8 GB for mouse

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v bwa-mem2` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run bwa-mem2` rather than bare `bwa-mem2`.

# Install with conda (recommended)
conda install -c bioconda bwa-mem2 samtools

# Or download pre-compiled binary
wget https://github.com/bwa-mem2/bwa-mem2/releases/download/v2.2.1/bwa-mem2-2.2.1_x64-linux.tar.bz2
tar -jxf bwa-mem2-2.2.1_x64-linux.tar.bz2
export PATH="$PWD/bwa-mem2-2.2.1_x64-linux:$PATH"

# Verify
bwa-mem2 version
# 2.2.1

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: reference_bundle
    kind: required
    source: user
    ask: "Which species and genome assembly should reads be aligned against?"
    default: null

  - id: D2
    param: read_group
    kind: required
    source: user
    ask: "What sample name and library identity should be stamped into each alignment?"
    default: null

  - id: D3
    param: downstream_compatibility
    kind: derived
    source: upstream
    ask: "Will GATK or Picard consume this BAM, requiring supplementary alignments flagged and soft-clipped?"
    default: "-M -Y when a GATK/Picard step follows"

  - id: D4
    param: seedLength
    kind: optional
    source: user
    ask: "Do these reads need a shorter seed than the default to map sensitively?"
    default: 19

  - id: D5
    param: minAlignmentScore
    kind: optional
    source: user
    ask: "How weak an alignment is still worth reporting?"
    default: 30

  - id: D6
    param: interleavedInput
    kind: derived
    source: data
    ask: "Are both mates held in a single interleaved FASTQ?"
    default: false
    skip_if: "reads supplied as separate R1/R2 files"

  - id: D7
    param: threads
    kind: never_ask
    source: data
    reason: "Affects runtime only, not the alignments"
    default: "min(8, available_cores)"

D2 is not cosmetic. The sample name in the read group is what joint genotyping groups by; an omitted or duplicated one silently merges or splits samples downstream, long after the alignment itself looks fine.

Quick Start

# 1. Build genome index (~30 min, run once)
bwa-mem2 index GRCh38.fa

# 2. Align paired-end reads and sort
bwa-mem2 mem -t 16 -R "@RG\tID:sample1\tSM:sample1\tPL:ILLUMINA" \
    GRCh38.fa sample1_R1.fastq.gz sample1_R2.fastq.gz \
    | samtools sort -@ 8 -o sample1.sorted.bam

# 3. Index the BAM
samtools index sample1.sorted.bam
echo "Aligned reads: $(samtools view -c -F 4 sample1.sorted.bam)"

Workflow

Step 1: Download Reference Genome

Obtain the reference genome FASTA file matching the target assembly.

# Download GRCh38 primary assembly (human)
wget https://ftp.ncbi.nlm.nih.gov/genomes/all/GCA/000/001/405/GCA_000001405.15_GRCh38/seqs_for_alignment_pipelines.ucsc_ids/GCA_000001405.15_GRCh38_no_alt_analysis_set.fna.gz
gunzip GCA_000001405.15_GRCh38_no_alt_analysis_set.fna.gz
mv GCA_000001405.15_GRCh38_no_alt_analysis_set.fna GRCh38.fa

# Or use ENSEMBL/GENCODE
wget https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_47/GRCh38.primary_assembly.genome.fa.gz
gunzip GRCh38.primary_assembly.genome.fa.gz

echo "Reference size: $(du -sh GRCh38.fa)"

Step 2: Build BWA-MEM2 Index

Index the reference genome — required once per genome, takes ~25-35 min for human.

# Build index (~28 GB RAM required for human genome)
bwa-mem2 index GRCh38.fa

# This creates: GRCh38.fa.0123, GRCh38.fa.amb, GRCh38.fa.ann,
#               GRCh38.fa.bwt.2bit.64, GRCh38.fa.pac
echo "Index files: $(ls GRCh38.fa.* | wc -l) created"
ls -lh GRCh38.fa.*

Step 3: Align Paired-End Reads

Align FASTQ reads with a read group header required for GATK compatibility.

# Align with read group (required for GATK)
# @RG fields: ID (run ID), SM (sample name), PL (platform), LB (library), PU (flowcell)
bwa-mem2 mem \
    -t 16 \
    -R "@RG\tID:sample1_run1\tSM:sample1\tPL:ILLUMINA\tLB:lib1\tPU:flowcell1" \
    GRCh38.fa \
    sample1_R1.fastq.gz \
    sample1_R2.fastq.gz \
    | samtools sort -@ 8 -m 2G -o sample1.sorted