Skip to content
Burrow-Wheeler Aligner for pairwise alignment between DNA sequences
C JavaScript Groff C++ Perl Shell Makefile
Failed to load latest commit information.
bwakit option to skip ALT Mar 16, 2016
.gitignore Added Makefile.bak and bwamem-lite to .gitignore Mar 13, 2013
.travis.yml removed coverity Oct 17, 2014
COPYING Imported from my local bwa repository, the master repository. Jan 13, 2011
ChangeLog Update to the latest modfication 0.5.9rc1-2. Update ChangeLog Jan 13, 2011
Makefile moved indexing to libbwa Feb 13, 2016
NEWS.md Released bwa-0.7.13 (r1126) Feb 23, 2016
QSufSort.c removed a few unused variables Feb 23, 2013
QSufSort.h move bwt_gen/* to the root directory Oct 20, 2011
README-alt.md changed download link: 0.7.11 => 0.7.12 Dec 29, 2014
README.md more FAQs on ALT mapping Dec 2, 2014
bamlite.c r837: removed BAM support Sep 16, 2014
bamlite.h r837: removed BAM support Sep 16, 2014
bntseq.c r896: more flexible ALT reading Oct 14, 2014
bntseq.h r816: read .alt file (not tested) Sep 5, 2014
bwa.1 Minor doc fix Mar 17, 2016
bwa.c r1130: changed "ah" to "AH" Apr 28, 2016
bwa.h moved indexing to libbwa Feb 13, 2016
bwamem.c removed the pbread mode Jan 26, 2016
bwamem.h removed the pbread mode Jan 27, 2016
bwamem_extra.c removed the pbread mode Jan 27, 2016
bwamem_pair.c r1038: wrong 0x100|0x800 flags in PE mode Dec 24, 2014
bwape.c Port #48 to the dev branch Feb 23, 2016
bwase.c added comment Feb 23, 2016
bwase.h removed color-space support Feb 12, 2013
bwaseqio.c r837: removed BAM support Sep 16, 2014
bwashm.c r912: very minor improvement Oct 17, 2014
bwt.c r941: set a min length for 3rd-round seeding Oct 21, 2014
bwt.h r941: set a min length for 3rd-round seeding Oct 21, 2014
bwt_gen.c r807: allow to change block size in bwt_gen Aug 25, 2014
bwt_lite.c r770: fixed a compiling warning May 14, 2014
bwt_lite.h Fixed clang compiling warnings Mar 16, 2014
bwtaln.c Release bwa-0.7.9-r782 May 19, 2014
bwtaln.h r397: multi changes/bugfixes to bwa-backtrack May 24, 2013
bwtgap.c r397: multi changes/bugfixes to bwa-backtrack May 24, 2013
bwtgap.h r397: multi changes/bugfixes to bwa-backtrack May 24, 2013
bwtindex.c moved indexing to libbwa Feb 13, 2016
bwtsw2.h r132: optionally copy FASTA/Q comment to SAM Oct 26, 2012
bwtsw2_aux.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
bwtsw2_chain.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
bwtsw2_core.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
bwtsw2_main.c Ensure exit status of 1 if given invalid options or index files are n… Apr 29, 2013
bwtsw2_pair.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
example.c minor change to example Oct 17, 2014
fastmap.c a typo in fastmap command-line prompt Feb 1, 2016
is.c Removed more dependencies on utils.h May 3, 2013
kbtree.h Release bwa-0.7.9-r782 May 19, 2014
khash.h Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
kopen.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
kseq.h r984: updated to the latest kseq.h Nov 13, 2014
ksort.h Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
kstring.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
kstring.h Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
ksw.c r744: int overflow given MB query May 1, 2014
ksw.h dev-448: different ins/del penalties Mar 28, 2014
kthread.c make kthread.c compiled with g++ Jan 26, 2016
kvec.h Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
main.c r1130: changed "ah" to "AH" Apr 28, 2016
malloc_wrap.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
malloc_wrap.h Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
maxk.c Include 'unistd.h' to explicitly declare 'getopt' Nov 14, 2015
pemerge.c Reduce dependency on utils.h - new malloc wrapping scheme. May 2, 2013
qualfa2fq.pl use /usr/env/perl Feb 23, 2016
rle.c ropebwt2 for bwt construction Jan 26, 2016
rle.h ropebwt2 for bwt construction Jan 26, 2016
rope.c ropebwt2 for bwt construction Jan 26, 2016
rope.h ropebwt2 for bwt construction Jan 26, 2016
utils.c r810: add err_puts() Aug 26, 2014
utils.h r810: add err_puts() Aug 26, 2014
xa2multi.pl use /usr/bin/env perl Feb 1, 2016

README.md

Build Status Build Status

Getting started

git clone https://github.com/lh3/bwa.git
cd bwa; make
./bwa index ref.fa
./bwa mem ref.fa read-se.fq.gz | gzip -3 > aln-se.sam.gz
./bwa mem ref.fa read1.fq read2.fq | gzip -3 > aln-pe.sam.gz

Introduction

BWA is a software package for mapping DNA sequences against a large reference genome, such as the human genome. It consists of three algorithms: BWA-backtrack, BWA-SW and BWA-MEM. The first algorithm is designed for Illumina sequence reads up to 100bp, while the rest two for longer sequences ranged from 70bp to a few megabases. BWA-MEM and BWA-SW share similar features such as the support of long reads and chimeric alignment, but BWA-MEM, which is the latest, is generally recommended as it is faster and more accurate. BWA-MEM also has better performance than BWA-backtrack for 70-100bp Illumina reads.

For all the algorithms, BWA first needs to construct the FM-index for the reference genome (the index command). Alignment algorithms are invoked with different sub-commands: aln/samse/sampe for BWA-backtrack, bwasw for BWA-SW and mem for the BWA-MEM algorithm.

Availability

BWA is released under GPLv3. The latest source code is freely available at github. Released packages can be downloaded at SourceForge. After you acquire the source code, simply use make to compile and copy the single executable bwa to the destination you want. The only dependency required to build BWA is zlib.

Since 0.7.11, precompiled binary for x86_64-linux is available in bwakit. In addition to BWA, this self-consistent package also comes with bwa-associated and 3rd-party tools for proper BAM-to-FASTQ conversion, mapping to ALT contigs, adapter triming, duplicate marking, HLA typing and associated data files.

Seeking helps

The detailed usage is described in the man page available together with the source code. You can use man ./bwa.1 to view the man page in a terminal. The HTML version of the man page can be found at the BWA website. If you have questions about BWA, you may sign up the mailing list and then send the questions to bio-bwa-help@sourceforge.net. You may also ask questions in forums such as BioStar and SEQanswers.

Citing BWA

  • Li H. and Durbin R. (2009) Fast and accurate short read alignment with Burrows-Wheeler transform. Bioinformatics, 25, 1754-1760. [PMID: 19451168]. (if you use the BWA-backtrack algorithm)

  • Li H. and Durbin R. (2010) Fast and accurate long-read alignment with Burrows-Wheeler transform. Bioinformatics, 26, 589-595. [PMID: 20080505]. (if you use the BWA-SW algorithm)

  • Li H. (2013) Aligning sequence reads, clone sequences and assembly contigs with BWA-MEM. arXiv:1303.3997v2 [q-bio.GN]. (if you use the BWA-MEM algorithm or the fastmap command, or want to cite the whole BWA package)

Please note that the last reference is a preprint hosted at arXiv.org. I do not have plan to submit it to a peer-reviewed journal in the near future.

Frequently asked questions (FAQs)

  1. What types of data does BWA work with?
  2. Why does a read appear multiple times in the output SAM?
  3. Does BWA work on reference sequences longer than 4GB in total?
  4. Why can one read in a pair has high mapping quality but the other has zero?
  5. How can a BWA-backtrack alignment stands out of the end of a chromosome?
  6. Does BWA work with ALT contigs in the GRCh38 release?
  7. Can I just run BWA-MEM against GRCh38+ALT without post-processing?

1. What types of data does BWA work with?

BWA works with a variety types of DNA sequence data, though the optimal algorithm and setting may vary. The following list gives the recommended settings:

  • Illumina/454/IonTorrent single-end reads longer than ~70bp or assembly contigs up to a few megabases mapped to a closely related reference genome:

      bwa mem ref.fa reads.fq > aln.sam
    
  • Illumina single-end reads shorter than ~70bp:

    bwa aln ref.fa reads.fq > reads.sai; bwa samse ref.fa reads.sai reads.fq > aln-se.sam
    
  • Illumina/454/IonTorrent paired-end reads longer than ~70bp:

    bwa mem ref.fa read1.fq read2.fq > aln-pe.sam
    
  • Illumina paired-end reads shorter than ~70bp:

    bwa aln ref.fa read1.fq > read1.sai; bwa aln ref.fa read2.fq > read2.sai
    bwa sampe ref.fa read1.sai read2.sai read1.fq read2.fq > aln-pe.sam
    
  • PacBio subreads or Oxford Nanopore reads to a reference genome:

    bwa mem -x pacbio ref.fa reads.fq > aln.sam
    bwa mem -x ont2d ref.fa reads.fq > aln.sam
    

BWA-MEM is recommended for query sequences longer than ~70bp for a variety of error rates (or sequence divergence). Generally, BWA-MEM is more tolerant with errors given longer query sequences as the chance of missing all seeds is small. As is shown above, with non-default settings, BWA-MEM works with Oxford Nanopore reads with a sequencing error rate over 20%.

2. Why does a read appear multiple times in the output SAM?

BWA-SW and BWA-MEM perform local alignments. If there is a translocation, a gene fusion or a long deletion, a read bridging the break point may have two hits, occupying two lines in the SAM output. With the default setting of BWA-MEM, one and only one line is primary and is soft clipped; other lines are tagged with 0x800 SAM flag (supplementary alignment) and are hard clipped.

3. Does BWA work on reference sequences longer than 4GB in total?

Yes. Since 0.6.x, all BWA algorithms work with a genome with total length over 4GB. However, individual chromosome should not be longer than 2GB.

4. Why can one read in a pair has high mapping quality but the other has zero?

This is correct. Mapping quality is assigned for individual read, not for a read pair. It is possible that one read can be mapped unambiguously, but its mate falls in a tandem repeat and thus its accurate position cannot be determined.

5. How can a BWA-backtrack alignment stands out of the end of a chromosome?

Internally BWA concatenates all reference sequences into one long sequence. A read may be mapped to the junction of two adjacent reference sequences. In this case, BWA-backtrack will flag the read as unmapped (0x4), but you will see position, CIGAR and all the tags. A similar issue may occur to BWA-SW alignment as well. BWA-MEM does not have this problem.

6. Does BWA work with ALT contigs in the GRCh38 release?

Yes, since 0.7.11, BWA-MEM officially supports mapping to GRCh38+ALT. BWA-backtrack and BWA-SW don't properly support ALT mapping as of now. Please see README-alt.md for details. Briefly, it is recommended to use bwakit, the binary release of BWA, for generating the reference genome and for mapping.

7. Can I just run BWA-MEM against GRCh38+ALT without post-processing?

If you are not interested in hits to ALT contigs, it is okay to run BWA-MEM without post-processing. The alignments produced this way are very close to alignments against GRCh38 without ALT contigs. Nonetheless, applying post-processing helps to reduce false mappings caused by reads from the diverged part of ALT contigs and also enables HLA typing. It is recommended to run the post-processing script.

Something went wrong with that request. Please try again.