Version Compatibility

Reference examples tested with: bowtie2 2.5+, 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.

Bowtie2 Alignment -- End-to-End vs Local and the Fragment-Geometry Flags Are the Whole Decision

"Align my ChIP-seq / ATAC-seq reads" -> Map short reads with Bowtie2, choosing whether the entire read must align (end-to-end) or read ends may be soft-clipped (local), and which fragment-geometry flags to set -- because for peak assays the mode, the preset, and the --no-mixed/--dovetail/-X flags determine the fragment coordinates the peak caller actually sees.

• CLI: bowtie2 -p 8 -x index -1 R1.fq.gz -2 R2.fq.gz | samtools sort -o aligned.bam -

Scope: DNA short-read mapping with Bowtie2 and the mode/preset/geometry choices that matter for ChIP/ATAC/CUT&RUN. Contig naming, the QC gate, and the cross-tool MAPQ scale -> alignment-files (bam-statistics / sam-bam-basics). Peak calling and the ATAC Tn5 cut-site shift -> chip-seq, atac-seq. BAM sort/dedup/stats -> alignment-files. Read trimming -> read-qc. OUT OF SCOPE: DNA variant calling (prefer bwa-alignment), RNA (star-alignment/hisat2-alignment), bisulfite (methylation-analysis/bismark-alignment -- Bismark wraps Bowtie2 internally, do not call Bowtie2 directly for WGBS).

The Single Most Important Modern Insight

1. End-to-end (default) vs --local is a biology decision about whether the full read must align. End-to-end forces the entire read to match (best score 0, no soft-clipping) -- correct for clean genomic DNA. --local soft-clips untrustworthy read ends to maximize score (positive match bonus) -- correct when read ends are junk: adapter read-through, the short fragments and frequent adapter contamination of ATAC-seq, or amplicon primer ends. Using end-to-end on adapter-contaminated reads mis-penalizes the good core and depresses the alignment rate; the fix is to trim first or use --local.
2. Bowtie2 MAPQ is a different scale from BWA and caps low. It is AS/XS-driven and discrete, capping at 42 in end-to-end mode and 44 in local mode -- it never reaches BWA's 60. A MAPQ >= 30 filter (the ENCODE ChIP/ATAC convention to drop multimappers) is fine, but a BWA-style MAPQ >= 60 "uniquely mapped" filter copied from a DNA-variant pipeline discards every Bowtie2 read. Always tune the MAPQ threshold to the aligner -- see alignment-files/sam-bam-basics for the full cross-tool table.
3. For peak assays, the fragment-geometry flags set the coordinates the peak caller consumes. ChIP/ATAC interpret signal at the fragment level (summits, fragment midpoints, nucleosome spacing), so a singleton ("mixed") or geometrically inconsistent (discordant) alignment injects a fragment with undefined length/position. --no-mixed --no-discordant restrict to concordant proper pairs; -X 2000 widens the allowed fragment length for ATAC's nucleosome-spanning fragments; --dovetail lets short-fragment pairs whose mates extend past each other still count as concordant (by default such pairs are not concordant and are dropped once --no-mixed/--no-discordant are set). These flags, not the core alignment, are what make the downstream peak set correct.

Tool Taxonomy

Decision Tree by Scenario

Default when uncertain: --very-sensitive end-to-end with --no-mixed --no-discordant for ChIP; switch to --local --dovetail -X 2000 for ATAC; filter -q 30 to drop multimappers.

Build Index

bowtie2-build --threads 8 reference.fa reference_index
# emits reference_index.{1,2,3,4}.bt2 and .rev.{1,2}.bt2. Pass the BASENAME (reference_index) to -x, NOT a file.

Basic Alignment

# Paired-end, streamed to a sorted BAM. Bowtie2 prints the alignment summary to stderr.
bowtie2 -p 8 -x reference_index -1 reads_1.fq.gz -2 reads_2.fq.gz 2> align.log | \
    samtools sort -@ 4 -o aligned.sorted.bam -
samtools index aligned.sorted.bam
# single-end: -U reads.fq.gz instead of -1/-2.

ChIP-seq

bowtie2 -p 8 --very-sensitive --no-mixed --no-discordant \
    --rg-id sample1 --rg SM:sample1 --rg PL:ILLUMINA --rg LB:lib1 \
    -x reference_index -1 chip_1.fq.gz -2 chip_2.fq.gz 2> chip.log | \
    samtools view -bS -q 30 -F 1804 - | \
    samtools sort -@ 4 -o chip.bam -
# -q 30 drops multimappers (Bowtie2 scale: max 42 e2e); -F 1804 removes unmapped/secondary/dup/QC-fail.

ATAC-seq

# Local mode + dovetail + wide -X for adapter read-through and nucleosome-spanning short fragments.
bowtie2 -p 8 --very-sensitive --local --dovetail -X 2000 --no-mixed --no-discordant \
    -x reference_index -1 atac_1.fq.gz -2 atac_2.fq.gz 2> atac.log | \
    samtools view -bS -q 30 -F 1804 - | \
    samtools sort -@ 4 -o atac.bam -
# The Tn5 +4/-5 cut-site shift is a DOWNSTREAM signal-track transform, not done here -> atac-seq.

Sensitivity Presets (end-to-end; the preset IS the speed/sensitivity decision)

bowtie2 --very-fast       -x index -1 r1.fq -2 r2.fq    # -D 5  -R 1 -N 0 -L 22 -i S,0,2.50
bowtie2 --sensitive       -x index -1 r1.fq -2 r2.fq    # -D 15 -R 2 -N 0 -L 22 -i S,1,1.15  (DEFAULT)
bowtie2 --very-sensitive  -x index -1 r1.fq -2 r2.fq    # -D 20 -R 3 -N 0 -L 20 -i S,1,0.50
# Append -local for the local-mode presets (e.g. --very-sensitive-local). Higher -D/-R/shorter -L = more sensitive, slower.

Multi-mapping and Unmapped Output

bowtie2 -k 5  -x index -1 r1.fq -2 r2.fq -S out.sam     # up to 5 alignments/read (MAPQ unreliable in -k)
bowtie2 -a    -x index -1 r1.fq -2 r2.fq -S out.sam     # ALL alignments (slow on repetitive genomes)
bowtie2 --un-conc-gz unmapped_%.fq.gz -x index -1 r1.fq.gz -2 r2.fq.gz -S out.sam  # save unaligned pairs

Key Parameters

Per-Method Failure Modes

End-to-end on adapter-contaminated reads

Trigger: untrimmed reads with adapter read-through aligned in default end-to-end mode. Mechanism: the contaminated 3' end forces mismatches the whole-read alignment cannot escape. Symptom: depressed alignment rate, lost reads at fragment ends. Fix: trim first (-> read-qc) or use --local to soft-clip the junk ends.

MAPQ filter copied from a BWA pipeline

Trigger: a MAPQ >= 60 "uniquely mapped" filter applied to Bowtie2 output. Mechanism: Bowtie2 caps at 42 (e2e) / 44 (local). Symptom: an empty BAM. Fix: use a tool-appropriate threshold (-q 30 drops multimappers) -> alignment-files/sam-bam-basics.

ATAC pairs flagged discordant

Trigger: ATAC alignment without --dovetail (and a too-tight -X). Mechanism: very short fragments produce mates that extend past each other, which default Bowtie2 does not count as concordant. Symptom: many real short-fragment pairs dropped by a --no-mixed/--no-discordant filter. Fix: add --dovetail and widen -X 2000.

-x given a filename

Trigger: -x referenceindex.1.bt2 (a file) instead of the basename. Mechanism: -x expects the index basename. Symptom: "Could not locate a Bowtie index" error. Fix: pass the basename (-x referenceindex).

Calling Bowtie2 directly for bisulfite data

Trigger: aligning WGBS reads with plain Bowtie2. Mechanism: bisulfite converts C->T, breaking 4-letter matching. Symptom: very low alignment rate, strand-biased mismatches. Fix: use Bismark, which wraps Bowtie2 with C->T-aware mapping -> methylation-analysis/bismark-alignment.

Quantitative Thresholds

Common Errors

References

• Langmead B, Salzberg SL. 2012. Fast gapped-read alignment with Bowtie 2. Nat Methods 9:357-359.
• Langmead B, Trapnell C, Pop M, Salzberg SL. 2009. Ultrafast and memory-efficient alignment of short DNA sequences to the human genome. Genome Biol 10:R25.
• Krueger F, Andrews SR. 2011. Bismark: a flexible aligner and methylation caller for Bisulfite-Seq applications. Bioinformatics 27:1571-1572.
• Vasimuddin M, Misra S, Li H, Aluru S. 2019. Efficient architecture-aware acceleration of BWA-MEM for multicore systems. IEEE IPDPS 2019:314-324.

Related Skills

• bwa-alignment - DNA variant-calling alignment with bwa-mem2 (ALT/decoy-aware)
• star-alignment - RNA splice-aware alignment (when reads cross junctions)
• read-qc/fastp-workflow - Trim adapters before end-to-end alignment
• alignment-files/duplicate-handling - Mark/remove duplicates after alignment
• alignment-files/sam-bam-basics - The cross-tool MAPQ scale, SAM flags, CIGAR
• alignment-files/bam-statistics - flagstat/idxstats QC gate; what a high mapping rate hides
• chip-seq/peak-calling - Call peaks from ChIP/CUT&RUN BAMs
• atac-seq/atac-peak-calling - ATAC peak calling and the Tn5 cut-site shift
• methylation-analysis/bismark-alignment - Bisulfite alignment (wraps Bowtie2)