Debian Codegraph @

bwa-apache2/README.md

raw
1 [![Build Status](https://github.com/lh3/bwa/actions/workflows/ci.yaml/badge.svg)](https://github.com/lh3/bwa/actions)
2 [![SourceForge Downloads](https://img.shields.io/sourceforge/dt/bio-bwa.svg?label=SF%20downloads)](https://sourceforge.net/projects/bio-bwa/files/?source=navbar)
3 [![GitHub Downloads](https://img.shields.io/github/downloads/lh3/bwa/total.svg?style=flat&label=GitHub%20downloads)](https://github.com/lh3/bwa/releases)
4 [![BioConda Install](https://img.shields.io/conda/dn/bioconda/bwa.svg?style=flag&label=BioConda%20install)](https://anaconda.org/bioconda/bwa)
5
6 **Note: [minimap2][minimap2] has replaced BWA-MEM for __PacBio and Nanopore__ read
7 alignment.** It retains all major BWA-MEM features, but is ~50 times as fast,
8 more versatile, more accurate and produces better base-level alignment.
9 A beta version of [BWA-MEM2][bwa-mem2] has been released for short-read mapping.
10 BWA-MEM2 is about twice as fast as BWA-MEM and outputs near identical alignments.
11
12 [minimap2]: https://github.com/lh3/minimap2
13 [bwa-mem2]: https://github.com/bwa-mem2/bwa-mem2
14
15 ## Getting started
16
17 git clone https://github.com/lh3/bwa.git
18 cd bwa; make
19 ./bwa index ref.fa
20 ./bwa mem ref.fa read-se.fq.gz | gzip -3 > aln-se.sam.gz
21 ./bwa mem ref.fa read1.fq read2.fq | gzip -3 > aln-pe.sam.gz
22
23 ## Introduction
24
25 BWA is a software package for mapping DNA sequences against a large reference
26 genome, such as the human genome. It consists of three algorithms:
27 BWA-backtrack, BWA-SW and BWA-MEM. The first algorithm is designed for Illumina
28 sequence reads up to 100bp, while the rest two for longer sequences ranged from
29 70bp to a few megabases. BWA-MEM and BWA-SW share similar features such as the
30 support of long reads and chimeric alignment, but BWA-MEM, which is the latest,
31 is generally recommended as it is faster and more accurate. BWA-MEM also has
32 better performance than BWA-backtrack for 70-100bp Illumina reads.
33
34 For all the algorithms, BWA first needs to construct the FM-index for the
35 reference genome (the **index** command). Alignment algorithms are invoked with
36 different sub-commands: **aln/samse/sampe** for BWA-backtrack,
37 **bwasw** for BWA-SW and **mem** for the BWA-MEM algorithm.
38
39 ## Availability
40
41 BWA is released under [Apache 2.0][1]. The latest source code is [freely
42 available at github][2]. Released packages can [be downloaded][3] at
43 SourceForge. After you acquire the source code, simply use `make` to compile
44 and copy the single executable `bwa` to the destination you want. The only
45 dependency required to build BWA is [zlib][14].
46
47 Since 0.7.11, precompiled binary for x86\_64-linux is available in [bwakit][17].
48 In addition to BWA, this self-consistent package also comes with bwa-associated
49 and 3rd-party tools for proper BAM-to-FASTQ conversion, mapping to ALT contigs,
50 adapter triming, duplicate marking, HLA typing and associated data files.
51
52 ## Seeking help
53
54 The detailed usage is described in the man page available together with the
55 source code. You can use `man ./bwa.1` to view the man page in a terminal. The
56 [HTML version][4] of the man page can be found at the [BWA website][5]. If you
57 have questions about BWA, you may [sign up the mailing list][6] and then send
58 the questions to [[email protected]][7]. You may also ask questions
59 in forums such as [BioStar][8] and [SEQanswers][9].
60
61 ## Citing BWA
62
63 * Li H. and Durbin R. (2009) Fast and accurate short read alignment with
64 Burrows-Wheeler transform. *Bioinformatics*, **25**, 1754-1760. [PMID:
65 [19451168][10]]. (if you use the BWA-backtrack algorithm)
66
67 * Li H. and Durbin R. (2010) Fast and accurate long-read alignment with
68 Burrows-Wheeler transform. *Bioinformatics*, **26**, 589-595. [PMID:
69 [20080505][11]]. (if you use the BWA-SW algorithm)
70
71 * Li H. (2013) Aligning sequence reads, clone sequences and assembly contigs
72 with BWA-MEM. [arXiv:1303.3997v2][12] [q-bio.GN]. (if you use the BWA-MEM
73 algorithm or the **fastmap** command, or want to cite the whole BWA package)
74
75 Please note that the last reference is a preprint hosted at [arXiv.org][13]. I
76 do not have plan to submit it to a peer-reviewed journal in the near future.
77
78 ## Frequently asked questions (FAQs)
79
80 1. [What types of data does BWA work with?](#type)
81 2. [Why does a read appear multiple times in the output SAM?](#multihit)
82 3. [Does BWA work on reference sequences longer than 4GB in total?](#4gb)
83 4. [Why can one read in a pair has high mapping quality but the other has zero?](#pe0)
84 5. [How can a BWA-backtrack alignment stands out of the end of a chromosome?](#endref)
85 6. [Does BWA work with ALT contigs in the GRCh38 release?](#altctg)
86 7. [Can I just run BWA-MEM against GRCh38+ALT without post-processing?](#postalt)
87
88 #### <a name="type"></a>1. What types of data does BWA work with?
89
90 BWA works with a variety types of DNA sequence data, though the optimal
91 algorithm and setting may vary. The following list gives the recommended
92 settings:
93
94 * Illumina/454/IonTorrent single-end reads longer than ~70bp or assembly
95 contigs up to a few megabases mapped to a closely related reference genome:
96
97 bwa mem ref.fa reads.fq > aln.sam
98
99 * Illumina single-end reads shorter than ~70bp:
100
101 bwa aln ref.fa reads.fq > reads.sai; bwa samse ref.fa reads.sai reads.fq > aln-se.sam
102
103 * Illumina/454/IonTorrent paired-end reads longer than ~70bp:
104
105 bwa mem ref.fa read1.fq read2.fq > aln-pe.sam
106
107 * Illumina paired-end reads shorter than ~70bp:
108
109 bwa aln ref.fa read1.fq > read1.sai; bwa aln ref.fa read2.fq > read2.sai
110 bwa sampe ref.fa read1.sai read2.sai read1.fq read2.fq > aln-pe.sam
111
112 * PacBio subreads or Oxford Nanopore reads to a reference genome:
113
114 bwa mem -x pacbio ref.fa reads.fq > aln.sam
115 bwa mem -x ont2d ref.fa reads.fq > aln.sam
116
117 BWA-MEM is recommended for query sequences longer than ~70bp for a variety of
118 error rates (or sequence divergence). Generally, BWA-MEM is more tolerant with
119 errors given longer query sequences as the chance of missing all seeds is small.
120 As is shown above, with non-default settings, BWA-MEM works with Oxford Nanopore
121 reads with a sequencing error rate over 20%.
122
123 #### <a name="multihit"></a>2. Why does a read appear multiple times in the output SAM?
124
125 BWA-SW and BWA-MEM perform local alignments. If there is a translocation, a gene
126 fusion or a long deletion, a read bridging the break point may have two hits,
127 occupying two lines in the SAM output. With the default setting of BWA-MEM, one
128 and only one line is primary and is soft clipped; other lines are tagged with
129 0x800 SAM flag (supplementary alignment) and are hard clipped.
130
131 #### <a name="4gb"></a>3. Does BWA work on reference sequences longer than 4GB in total?
132
133 Yes. Since 0.6.x, all BWA algorithms work with a genome with total length over
134 4GB. However, individual chromosome should not be longer than 2GB.
135
136 #### <a name="pe0"></a>4. Why can one read in a pair have a high mapping quality but the other has zero?
137
138 This is correct. Mapping quality is assigned for individual read, not for a read
139 pair. It is possible that one read can be mapped unambiguously, but its mate
140 falls in a tandem repeat and thus its accurate position cannot be determined.
141
142 #### <a name="endref"></a>5. How can a BWA-backtrack alignment stand out of the end of a chromosome?
143
144 Internally BWA concatenates all reference sequences into one long sequence. A
145 read may be mapped to the junction of two adjacent reference sequences. In this
146 case, BWA-backtrack will flag the read as unmapped (0x4), but you will see
147 position, CIGAR and all the tags. A similar issue may occur to BWA-SW alignment
148 as well. BWA-MEM does not have this problem.
149
150 #### <a name="altctg"></a>6. Does BWA work with ALT contigs in the GRCh38 release?
151
152 Yes, since 0.7.11, BWA-MEM officially supports mapping to GRCh38+ALT.
153 BWA-backtrack and BWA-SW don't properly support ALT mapping as of now. Please
154 see [README-alt.md][18] for details. Briefly, it is recommended to use
155 [bwakit][17], the binary release of BWA, for generating the reference genome
156 and for mapping.
157
158 #### <a name="postalt"></a>7. Can I just run BWA-MEM against GRCh38+ALT without post-processing?
159
160 If you are not interested in hits to ALT contigs, it is okay to run BWA-MEM
161 without post-processing. The alignments produced this way are very close to
162 alignments against GRCh38 without ALT contigs. Nonetheless, applying
163 post-processing helps to reduce false mappings caused by reads from the
164 diverged part of ALT contigs and also enables HLA typing. It is recommended to
165 run the post-processing script.
166
167
168
169 [1]: http://en.wikipedia.org/wiki/GNU_General_Public_License
170 [2]: https://github.com/lh3/bwa
171 [3]: http://sourceforge.net/projects/bio-bwa/files/
172 [4]: http://bio-bwa.sourceforge.net/bwa.shtml
173 [5]: http://bio-bwa.sourceforge.net/
174 [6]: https://lists.sourceforge.net/lists/listinfo/bio-bwa-help
175 [7]: mailto:[email protected]
176 [8]: http://biostars.org
177 [9]: http://seqanswers.com/
178 [10]: http://www.ncbi.nlm.nih.gov/pubmed/19451168
179 [11]: http://www.ncbi.nlm.nih.gov/pubmed/20080505
180 [12]: http://arxiv.org/abs/1303.3997
181 [13]: http://arxiv.org/
182 [14]: http://zlib.net/
183 [15]: https://github.com/lh3/bwa/tree/mem
184 [16]: ftp://ftp.ncbi.nlm.nih.gov/genbank/genomes/Eukaryotes/vertebrates_mammals/Homo_sapiens/GRCh38/seqs_for_alignment_pipelines/
185 [17]: http://sourceforge.net/projects/bio-bwa/files/bwakit/
186 [18]: https://github.com/lh3/bwa/blob/master/README-alt.md