BBMap

Overview

BBMap is designed for accurate mapping of sequencing reads to reference genomes, particularly effective with highly mutated genomes or reads containing long indels (including whole-gene deletions over 100kbp). It has no upper limit on genome size or contig number, successfully mapping to genomes as large as 85 gigabases with over 200 million contigs.

The aligner can output comprehensive statistics including empirical read quality histograms, insert-size distributions, and genome coverage statistics, making it valuable for quality control of libraries and sequencing runs, or evaluating new sequencing platforms.

Basic Usage

bbmap.sh ref=<fasta> in=<reads> out=<sam>

Index only: bbmap.sh ref=<fasta>

Map to existing index: bbmap.sh in=<reads> out=<sam>

Map without writing index: bbmap.sh ref=<fasta> in=<reads> out=<sam> nodisk

Standard input/output: in=stdin will accept reads from standard input, and out=stdout will write to standard output. File extensions are still needed to specify the format, e.g., in=stdin.fa.gz will read gzipped fasta from standard input.

Index Management

BBMap requires indexing the reference before mapping. The index location and management follows specific patterns:

Index Location and Build System

By default, BBMap writes indices to a /ref/ subdirectory of your current working directory. If you run BBMap from /home/user/work/, the index will be written to /home/user/work/ref/. Multiple references can be indexed in the same directory using build numbers.

Index Workflow Examples

# Build index for reference A
bbmap.sh ref=A.fa
# Index written to ./ref/ as build 1

# Map to existing index
bbmap.sh in=reads.fq out=mapped.sam
# Loads existing index from ./ref/

# Build second reference with specific build number
bbmap.sh ref=B.fa build=2
# Index written to ./ref/ as build 2

# Build index in custom location
bbmap.sh ref=C.fa path=/custom/location/
# Index written to /custom/location/ref/

Important: Do not have multiple processes write an index to the same location simultaneously, as this will create a corrupt index that must be deleted and regenerated. Use the nodisk flag for parallel mapping jobs, or build the index once and then map multiple files simultaneously.

Memory Management

BBMap memory usage is predictable and scales with reference genome size:

• Normal mode: ~6 bytes per reference base
• Low-memory mode: ~3 bytes per reference base (use usemodulo flag)
• Human genome: ~24GB RAM normally, ~12GB with usemodulo
• Thread memory: Additional memory per thread for alignment matrices

Memory usage increases with kmer length. To estimate memory requirements for a specific kmer length, run stats.sh in=reference.fa k=13 before indexing.

Low-Memory Mode

The usemodulo flag reduces memory usage by ~50% with slight sensitivity reduction by discarding ~80% of kmers based on modulo arithmetic. This flag must be used both during indexing and mapping:

# Build low-memory index
bbmap.sh ref=reference.fa usemodulo

# Map using low-memory index
bbmap.sh in=reads.fq out=mapped.sam usemodulo

Parameters

BBMap supports over 140 parameters organized by function. Parameters are grouped to match their role in the mapping process.

Common Usage Scenarios

bbmap.sh ref=reference.fa in=reads.fq out=mapped.sam

bbmap.sh ref=genome.fa in=reads.fq out=mapped.sam maxindel=200k ambig=random intronlen=20 xstag=us

bbmap.sh ref=reference.fa in=reads.fq out=mapped.sam slow k=12

bbmap.sh ref=reference.fa in=reads.fq out=mapped.sam fast

bbmap.sh ref=contaminant.fa in=reads.fq outm=contaminated.fq outu=clean.fq \
  minratio=0.9 maxindel=3 bwr=0.16 bw=12 fast minhits=2 qtrim=r trimq=10 \
  untrim idtag printunmappedcount kfilter=25 maxsites=1 k=14

bbmap.sh ref=reference.fa in=reads.fq \
  covstats=coverage_stats.txt covhist=coverage_histogram.txt \
  basecov=per_base_coverage.txt bincov=binned_coverage.txt

# First, build low-memory index
bbmap.sh ref=reference.fa usemodulo

# Then map with same setting
bbmap.sh in=reads.fq out=mapped.sam usemodulo

# Build multiple indices in same directory
bbmap.sh ref=human.fa build=1
bbmap.sh ref=mouse.fa build=2
bbmap.sh ref=virus.fa build=3

# Map to specific index
bbmap.sh in=reads.fq out=mapped.sam build=2

bbmap.sh ref=reference.fa in=reads.fq out=mapped.sam bamscript=sort_bam.sh
sh sort_bam.sh

Algorithm Details

Multi-Kmer-Seed-and-Extend Algorithm

BBMap uses a multi-kmer-seed-and-extend approach, described by the algorithm's creator as analogous to growing polycrystalline silicon. This method provides superior accuracy compared to single-seed approaches, particularly for highly mutated genomes and reads with complex indel patterns.

Global vs Local Alignment

BBMap is fundamentally a global aligner, meaning it seeks the highest-scoring alignment considering all bases in a sequence. This approach is essential for detecting long indels that local aligners might miss by clipping sequence ends. When the local flag is used, BBMap still performs global alignment internally but converts results to local alignments by clipping low-scoring ends.

Scoring System and Identity Calculation

BBMap uses a custom affine-transform scoring matrix rather than simple percent identity. The mapping decision depends on whether the ratio between the actual alignment score and the maximum possible score exceeds the minratio threshold:

• Match: +100 points
• First mismatch: -127 points
• Consecutive mismatch: -51 points
• Variable penalties: Based on mutation event length and type (substitution vs indel)

The minid parameter provides user-friendly control by automatically calculating the appropriate minratio value. For example, minid=0.9 sets minratio=0.816 based on the expected score ratio for 90% identity with noncontiguous substitutions.

Performance Modes

BBMap implements three performance presets that adjust multiple parameters simultaneously:

Fast Mode

Optimized for speed at reduced sensitivity (bad for RNA-seq):

• Reduces tip search distance (tipsearch=20)
• Limits indel detection (maxindel=80)
• Increases seed requirements (minhits=2)
• Restricts alignment bandwidth (bwr=0.18)
• Excludes more frequent kmers (excludefraction*1.25)
• Reduces key density (keyDensity*0.9)

Slow Mode

Enhanced sensitivity for challenging data:

• Increases tip search distance (tipsearch=150)
• Lowers seed requirements (minhits=1)
• Reduces minimum alignment ratio (minratio=0.45)
• Includes more kmers (excludefraction*0.4)
• Increases key density (keyDensity*1.2)

VSlow Mode

Maximum sensitivity for divergent sequences:

• Disables quality filtering (usequality=false)
• Very low alignment threshold (minratio=0.22)
• No kmer exclusion (excludefraction=0)
• Maximum key density (keyDensity*2.5)
• Extended rescue distance (rescuedist=2500)

Memory Architecture

BBMap's memory usage follows predictable patterns based on reference genome size and kmer length:

• Index storage: ~6 bytes per reference base (normal mode)
• Low-memory mode: ~3 bytes per reference base with usemodulo
• Thread overhead: Additional memory per thread for alignment matrices
• Kmer length scaling: Memory increases with longer kmers

The system automatically adjusts parameters based on genome size: genomes under 30MB get enhanced hit reduction and exclusion fraction adjustments, while larger genomes use standard parameters.

Index Management System

BBMap implements a sophisticated index management system that handles multiple references efficiently:

• Automatic detection: Checks for existing compatible indices before building
• Build numbering: Supports multiple indices in the same directory using build IDs
• Path customization: Allows custom index locations via the path parameter
• Disk vs memory: Can build indices in memory only (nodisk) or persist to disk

RNA-seq Specific Features

BBMap includes specific optimizations for RNA-seq data:

• Splice junction detection: Uses maxindel parameter to detect long introns
• Strand-specific mapping: XS tag generation for firststrand/secondstrand/unstranded protocols
• Intron annotation: Converts long deletions to introns (N) in CIGAR strings based on intronlen threshold
• Rescue operations: Performs brute-force search for poorly mapping paired reads

File Format Support

Input formats: FASTA, FASTQ (compressed or uncompressed). Paired reads can be in two files or interleaved in a single file.

Output formats: FASTA, FASTQ, SAM, BAM (if samtools is installed). Alignment information is preserved only in SAM/BAM formats.

Compression: Supports gzip, bgzip, and can utilize pigz for parallel compression/decompression.

SAM Format Compatibility

BBMap supports both modern SAM 1.4 specification (default) and legacy SAM 1.3 format:

• SAM 1.4 (default): Uses X for substitutions, = for matches
• SAM 1.3 (legacy): Uses M for both matches and mismatches (use sam=1.3 flag)

Some older programs require the sam=1.3 flag and trd (trimreaddescriptions) for compatibility.

Performance Considerations

BBMap scales near-linearly with processor cores and is optimized for both indexing and mapping phases. Performance can be tuned based on specific requirements:

Speed Optimization

• Increase minhits and kmer length
• Use fast flag for macro optimization
• Reduce maxindel for faster alignment
• Adjust sensitivity flags like minratio and bandwidth

Sensitivity Optimization

• Use slow or vslow flags
• Decrease kmer length (k=12 or lower)
• Lower minratio threshold
• Increase maxindel for long indel detection

Memory Optimization

• Use usemodulo flag to reduce index size by ~50%
• Adjust thread count based on available memory
• Consider nodisk for temporary mappings

Related Tools

• BBSplit: Maps reads to multiple genomes simultaneously, determining best matches
• BBWrap: Wrapper for running BBMap multiple times without reloading the index
• mapPacBio.sh: Variant optimized for long reads (PacBio/Nanopore) up to 6kbp
• BBMapSkimmer: Finds all alignments above a threshold rather than single best alignment

Support

For questions and support:

• Author: Brian Bushnell
• Email: bbushnell@lbl.gov
• Forum: SeqAnswers
• Documentation: bbmap.org