Debian Codegraph @

MANUAL.markdown

raw
1 <!--
2 ! This manual is written in "markdown" format and thus contains some
3 ! distracting formatting clutter. See 'MANUAL' for an easier-to-read version
4 ! of this text document, or see the HTML manual online.
5 ! -->
6
7 Introduction
8 ============
9
10 [Bowtie 2] is an ultrafast and memory-efficient tool for aligning sequencing
11 reads to long reference sequences. It is particularly good at aligning reads of
12 about 50 up to 100s of characters to relatively long (e.g. mammalian)
13 genomes. Bowtie 2 indexes the genome with an [FM Index][FM Index Wiki] (based on the
14 [Burrows-Wheeler Transform] or [BWT]) to keep its memory footprint small: for
15 the human genome, its memory footprint is typically around 3.2 gigabytes of RAM.
16 Bowtie 2 supports gapped, local, and paired-end alignment modes. Multiple
17 processors can be used simultaneously to achieve greater alignment speed.
18
19 Bowtie 2 outputs alignments in [SAM] format, enabling interoperation with a
20 large number of other tools (e.g. [SAMtools], [GATK]) that use SAM. Bowtie 2 is
21 distributed under the [GPLv3 license], and it runs on the command line under
22 Windows, Mac OS X and Linux and BSD.
23
24 [Bowtie 2] is often the first step in pipelines for comparative genomics,
25 including for variation calling, ChIP-seq, RNA-seq, BS-seq. [Bowtie 2] and
26 [Bowtie] (also called "[Bowtie 1]" here) are also tightly integrated into many
27 other tools, some of which [are listed here](http://bowtie-bio.sourceforge.net/bowtie2/other_tools.shtml).
28
29 If you use [Bowtie 2] for your published research, please cite our work. Papers
30 describing Bowtie 2 are:
31
32 * Langmead B, Wilks C, Antonescu V, Charles R. [Scaling read aligners to hundreds
33 of threads on general-purpose processors](https://doi.org/10.1093/bioinformatics/bty648). _Bioinformatics_. 2018 Jul 18. doi:
34 10.1093/bioinformatics/bty648.
35
36 * Langmead B, Salzberg SL. [Fast gapped-read alignment with Bowtie 2](https://www.nature.com/articles/nmeth.1923). _Nature
37 Methods_. 2012 Mar 4;9(4):357-9. doi: 10.1038/nmeth.1923.
38
39
40 How is Bowtie 2 different from Bowtie 1?
41 ----------------------------------------
42
43 Bowtie 1 was released in 2009 and was geared toward aligning the relatively
44 short sequencing reads (up to 25-50 nucleotides) prevalent at the time. Since
45 then, technology has improved both sequencing throughput (more nucleotides
46 produced per sequencer per day) and read length (more nucleotides per read).
47
48 The chief differences between Bowtie 1 and Bowtie 2 are:
49
50 1. For reads longer than about 50 bp Bowtie 2 is generally faster, more
51 sensitive, and uses less memory than Bowtie 1. For relatively short reads (e.g.
52 less than 50 bp) Bowtie 1 is sometimes faster and/or more sensitive.
53
54 2. Bowtie 2 supports gapped alignment with affine gap penalties. Number of gaps
55 and gap lengths are not restricted, except by way of the configurable scoring
56 scheme. Bowtie 1 finds just ungapped alignments.
57
58 3. Bowtie 2 supports [local alignment], which doesn't require reads to align
59 end-to-end. Local alignments might be "trimmed" ("soft clipped") at one or both
60 extremes in a way that optimizes alignment score. Bowtie 2 also supports
61 [end-to-end alignment] which, like Bowtie 1, requires that the read align
62 entirely.
63
64 4. There is no upper limit on read length in Bowtie 2. Bowtie 1 had an upper
65 limit of around 1000 bp.
66
67 5. Bowtie 2 allows alignments to [overlap ambiguous characters] (e.g. `N`s) in
68 the reference. Bowtie 1 does not.
69
70 6. Bowtie 2 does away with Bowtie 1's notion of alignment "stratum", and its
71 distinction between "Maq-like" and "end-to-end" modes. In Bowtie 2 all
72 alignments lie along a continuous spectrum of alignment scores where the
73 [scoring scheme], similar to [Needleman-Wunsch] and [Smith-Waterman].
74
75 7. Bowtie 2's [paired-end alignment] is more flexible. E.g. for pairs that do
76 not align in a paired fashion, Bowtie 2 attempts to find unpaired alignments for
77 each mate.
78
79 8. Bowtie 2 reports a spectrum of mapping qualities, in contrast for Bowtie 1
80 which reports either 0 or high.
81
82 9. Bowtie 2 does not align colorspace reads.
83
84 Bowtie 2 is not a "drop-in" replacement for Bowtie 1. Bowtie 2's command-line
85 arguments and genome index format are both different from Bowtie 1's.
86
87
88 What isn't Bowtie 2?
89 --------------------
90
91 Bowtie 2 is geared toward aligning relatively short sequencing reads to long
92 genomes. That said, it handles arbitrarily small reference sequences (e.g.
93 amplicons) and very long reads (i.e. upwards of 10s or 100s of kilobases),
94 though it is slower in those settings. It is optimized for the read lengths
95 and error modes yielded by typical Illumina sequencers.
96
97 Bowtie 2 does not support alignment of colorspace reads. (Bowtie 1 does.)
98
99
100 Obtaining Bowtie 2
101 ==================
102
103 Bowtie 2 is available from various package managers, notably [Bioconda](https://anaconda.org/bioconda/bowtie2).
104 With Bioconda installed, you should be able to install Bowtie 2 with `conda
105 install bowtie2`.
106
107 You can also download Bowtie 2 sources and binaries from the
108 [Download] section of the Sourceforge site. Binaries are available
109 for the `x86_64` architecture running Linux, Mac OS X, and Windows.
110 FreeBSD users can obtain the latest version of Bowtie 2 from ports
111 using `pkg install bowtie2`. If you plan to compile Bowtie 2 yourself,
112 make sure to get the source package, i.e., the filename that ends
113 in "-source.zip".
114
115 Building from source
116 --------------------
117 Building from source
118
119 Building Bowtie 2 from source requires a GNU-like environment with
120 Clang/GCC, GNU Make and other basics. It should be possible to build
121 Bowtie 2 on most vanilla *NIX installations or on a Mac installation
122 with Xcode installed.
123 Bowtie 2 can also be built on Windows using a 64-bit MinGW distribution
124 and MSYS. In order to simplify the MinGW setup it might be worth
125 investigating popular MinGW personal builds since these are coming
126 already prepared with most of the toolchains needed.
127
128 First, download the source package from the [sourceforge site]. Make sure
129 you're getting the source package; the file downloaded should end in
130 `-source.zip`. Unzip the file, change to the unzipped directory, and build the
131 Bowtie 2 tools by running GNU `make` (usually with the command `make`, but
132 sometimes with `gmake`) with no arguments. If building with MinGW, run `make`
133 from the MSYS environment.
134
135 The Bowtie 2 Makefile also includes recipes for basic automatic dependency
136 management. Running `make static-libs && make STATIC_BUILD=1` will issue
137 a series of commands that will:
138 1. download zstd and zlib
139 2. compile them as static libraries
140 3. link the resulting libraries to the compiled Bowtie 2 binaries
141
142 ### Building with SRA support ###
143
144 As of version 2.3.5 bowtie2 now supports aligning SRA reads. Prepackaged
145 builds will include a package that supports SRA. If you're building bowtie2
146 from source please make sure that the Java runtime is available on your system.
147 You can then proceed with the build by running `make sra-deps && make USE_SRA=1`.
148
149 ### Building with libsais support ###
150
151 As of version 2.5.3 `bowtie2` supports building indexes using the SAIS algorithm
152 provided by [libsais]. SAIS is a state-of-the-art suffix array construction algorithm
153 that will bring-forth a significant speed-up to the overall index building process.
154 There is, however, the downside of a significant increase in memory usage compared
155 to the persistent blockwise algorithm that `bowtie2-build` uses by default. When using
156 SAIS small indexes can be built for inputs up to 2GB. The `bowtie2-build` wrapper
157 will help determine the appropriate index type for uncompressed and gzipped inputs.
158
159 To build `bowtie2-build` with [libsais] first make sure that the libsais submodule
160 is available. This can be done in one of the following ways:
161
162 * first time cloning bowtie2 -- `git clone --recursive https://github.com/BenLangmead/bowtie2.git`
163 * existing checkout of bowtie2 -- `git submodule init && git submodule update`
164
165 Issue the following command line to build libsais:
166
167 * with OpenMP support -- `[g]make libsais USE_SAIS_OPENMP=1`
168 * without OpenMP support -- `[g]make libsais USE_SAIS=1`
169
170 The choice of using OpenMP will determine whether or not the algorithm
171 runs multithreaded. The [`-p/--threads`] argument to `bowtie2-build` will
172 be ignored when libsais is compiled without OpenMP support.
173
174 Finally, building the bowtie2-build executable:
175
176 * with OpenMP support -- `[g]make bowtie2-build-s USE_SAIS_OPENMP=1`
177 * without OpenMP support -- `[g]make bowtie2-build-s USE_SAIS=1`
178
179 ### Building with CMake ###
180
181 To build Bowtie2 with SRA and libsais support issue the following command:
182
183 * `cmake . -D USE_SRA=1 -D USE_SAIS=1 && cmake --build .`
184
185 CMake will take care of building and linking against the specified dependencies.
186
187 Adding to PATH
188 --------------
189
190 By adding your new Bowtie 2 directory to your [PATH environment variable], you
191 ensure that whenever you run `bowtie2`, `bowtie2-build` or `bowtie2-inspect`
192 from the command line, you will get the version you just installed without
193 having to specify the entire path. This is recommended for most users. To do
194 this, follow your operating system's instructions for adding the directory to
195 your [PATH].
196
197 If you would like to install Bowtie 2 by copying the Bowtie 2 executable files
198 to an existing directory in your [PATH], make sure that you copy all the
199 executables, including `bowtie2`, `bowtie2-align-s`, `bowtie2-align-l`,
200 `bowtie2-build`, `bowtie2-build-s`, `bowtie2-build-l`, `bowtie2-inspect`,
201 `bowtie2-inspect-s` and `bowtie2-inspect-l`.
202
203
204 The `bowtie2` aligner
205 =====================
206
207 `bowtie2` takes a Bowtie 2 index and a set of sequencing read files and outputs
208 a set of alignments in SAM format.
209
210 "Alignment" is the process by which we discover how and where the read sequences
211 are similar to the reference sequence. An "alignment" is a result from this
212 process, specifically: an alignment is a way of "lining up" some or all of the
213 characters in the read with some characters from the reference in a way that
214 reveals how they're similar. For example:
215
216 Read: GACTGGGCGATCTCGACTTCG
217 ||||| |||||||||| |||
218 Reference: GACTG--CGATCTCGACATCG
219
220 Where dash symbols represent gaps and vertical bars show where aligned
221 characters match.
222
223 We use alignment to make an educated guess as to where a read originated with
224 respect to the reference genome. It's not always possible to determine this
225 with certainty. For instance, if the reference genome contains several long
226 stretches of As (`AAAAAAAAA` etc.) and the read sequence is a short stretch of As
227 (`AAAAAAA`), we cannot know for certain exactly where in the sea of `A`s the
228 read originated.
229
230 End-to-end alignment versus local alignment
231 -------------------------------------------
232
233 By default, Bowtie 2 performs end-to-end read alignment. That is, it searches
234 for alignments involving all of the read characters. This is also called an
235 "untrimmed" or "unclipped" alignment.
236
237 When the --local option is specified, Bowtie 2 performs local read alignment. In
238 this mode, Bowtie 2 might "trim" or "clip" some read characters from one or both
239 ends of the alignment if doing so maximizes the alignment score.
240
241 ### End-to-end alignment example
242
243 The following is an "end-to-end" alignment because it involves all the
244 characters in the read. Such an alignment can be produced by Bowtie 2 in either
245 end-to-end mode or in local mode.
246
247 Read: GACTGGGCGATCTCGACTTCG
248 Reference: GACTGCGATCTCGACATCG
249
250 Alignment:
251 Read: GACTGGGCGATCTCGACTTCG
252 ||||| |||||||||| |||
253 Reference: GACTG--CGATCTCGACATCG
254
255 ### Local alignment example
256
257 The following is a "local" alignment because some of the characters at the ends
258 of the read do not participate. In this case, 4 characters are omitted (or
259 "soft trimmed" or "soft clipped") from the beginning and 3 characters are
260 omitted from the end. This sort of alignment can be produced by Bowtie 2 only
261 in local mode.
262
263 Read: ACGGTTGCGTTAATCCGCCACG
264 Reference: TAACTTGCGTTAAATCCGCCTGG
265
266 Alignment:
267 Read: ACGGTTGCGTTAA-TCCGCCACG
268 ||||||||| ||||||
269 Reference: TAACTTGCGTTAAATCCGCCTGG
270
271 Scores: higher = more similar
272 -----------------------------
273
274 An alignment score quantifies how similar the read sequence is to the reference
275 sequence aligned to. The higher the score, the more similar they are. A score
276 is calculated by subtracting penalties for each difference (mismatch, gap, etc.)
277 and, in local alignment mode, adding bonuses for each match.
278
279 The scores can be configured with the [`--ma`] (match bonus), [`--mp`] (mismatch
280 penalty), [`--np`] (penalty for having an N in either the read or the
281 reference), [`--rdg`] (affine read gap penalty) and [`--rfg`] (affine reference
282 gap penalty) options.
283
284 ### End-to-end alignment score example
285
286 A mismatched base at a high-quality position in the read receives a penalty of
287 -6 by default. A length-2 read gap receives a penalty of -11 by default (-5 for
288 the gap open, -3 for the first extension, -3 for the second extension). Thus,
289 in end-to-end alignment mode, if the read is 50 bp long and it matches the
290 reference exactly except for one mismatch at a high-quality position and one
291 length-2 read gap, then the overall score is -(6 + 11) = -17.
292
293 The best possible alignment score in end-to-end mode is 0, which happens when
294 there are no differences between the read and the reference.
295
296 ### Local alignment score example
297
298 A mismatched base at a high-quality position in the read receives a penalty of
299 -6 by default. A length-2 read gap receives a penalty of -11 by default (-5 for
300 the gap open, -3 for the first extension, -3 for the second extension). A base
301 that matches receives a bonus of +2 be default. Thus, in local alignment mode,
302 if the read is 50 bp long and it matches the reference exactly except for one
303 mismatch at a high-quality position and one length-2 read gap, then the overall
304 score equals the total bonus, 2 * 49, minus the total penalty, 6 + 11, = 81.
305
306 The best possible score in local mode equals the match bonus times the length of
307 the read. This happens when there are no differences between the read and the
308 reference.
309
310 ### Valid alignments meet or exceed the minimum score threshold
311
312 For an alignment to be considered "valid" (i.e. "good enough") by Bowtie 2, it
313 must have an alignment score no less than the minimum score threshold. The
314 threshold is configurable and is expressed as a function of the read length. In
315 end-to-end alignment mode, the default minimum score threshold is `-0.6 + -0.6 *
316 L`, where `L` is the read length. In local alignment mode, the default minimum
317 score threshold is `20 + 8.0 * ln(L)`, where L is the read length. This can be
318 configured with the [`--score-min`] option. For details on how to set options
319 like `--score-min` that correspond to functions, see the section on [setting
320 function options].
321
322
323 Mapping quality: higher = more unique
324 -------------------------------------
325
326 The aligner cannot always assign a read to its point of origin with high
327 confidence. For instance, a read that originated inside a repeat element might
328 align equally well to many occurrences of the element throughout the genome,
329 leaving the aligner with no basis for preferring one over the others.
330
331 Aligners characterize their degree of confidence in the point of origin by
332 reporting a mapping quality: a non-negative integer Q = -10 log10 p, where p is
333 an estimate of the probability that the alignment does not correspond to the
334 read's true point of origin. Mapping quality is sometimes abbreviated MAPQ, and
335 is recorded in the [SAM] `MAPQ` field.
336
337 Mapping quality is related to "uniqueness." We say an alignment is unique if it
338 has a much higher alignment score than all the other possible alignments. The
339 bigger the gap between the best alignment's score and the second-best
340 alignment's score, the more unique the best alignment, and the higher its mapping
341 quality should be.
342
343 Accurate mapping qualities are useful for downstream tools like variant callers.
344 For instance, a variant caller might choose to ignore evidence from alignments
345 with mapping quality less than, say, 10. A mapping quality of 10 or less
346 indicates that there is at least a 1 in 10 chance that the read truly originated
347 elsewhere.
348
349
350 Aligning pairs
351 --------------
352
353 A "paired-end" or "mate-pair" read consists of pair of mates, called mate 1 and
354 mate 2. Pairs come with a prior expectation about (a) the relative orientation
355 of the mates, and (b) the distance separating them on the original DNA molecule.
356 Exactly what expectations hold for a given dataset depends on the lab procedures
357 used to generate the data. For example, a common lab procedure for producing
358 pairs is Illumina's Paired-end Sequencing Assay, which yields pairs with a
359 relative orientation of FR ("forward, reverse") meaning that if mate 1 came from
360 the Watson strand, mate 2 very likely came from the Crick strand and vice versa.
361 Also, this protocol yields pairs where the expected genomic distance from end
362 to end is about 200-500 base pairs.
363
364 For simplicity, this manual uses the term "paired-end" to refer to any pair of
365 reads with some expected relative orientation and distance. Depending on the
366 protocol, these might actually be referred to as "paired-end" or "mate-paired."
367 Also, we always refer to the individual sequences making up the pair as "mates."
368
369 ### Paired inputs
370
371 Pairs are often stored in a pair of files, one file containing the mate 1s and
372 the other containing the mates 2s. The first mate in the file for mate 1 forms
373 a pair with the first mate in the file for mate 2, the second with the second,
374 and so on. When aligning pairs with Bowtie 2, specify the file with the mate 1s
375 mates using the [`-1`] argument and the file with the mate 2s using the [`-2`]
376 argument. This causes Bowtie 2 to take the paired nature of the reads into
377 account when aligning them.
378
379 ### Paired SAM output
380
381 When Bowtie 2 prints a SAM alignment for a pair, it prints two records (i.e. two
382 lines of output), one for each mate. The first record describes the alignment
383 for mate 1 and the second record describes the alignment for mate 2. In both
384 records, some of the fields of the SAM record describe various properties of the
385 alignment; for instance, the 7th and 8th fields (`RNEXT` and `PNEXT`
386 respectively) indicate the reference name and position where the other mate
387 aligned, and the 9th field indicates the inferred length of the DNA fragment
388 from which the two mates were sequenced. See the [SAM specification] for more
389 details regarding these fields.
390
391 ### Concordant pairs match pair expectations, discordant pairs don't
392
393 A pair that aligns with the expected relative mate orientation and with the
394 expected range of distances between mates is said to align "concordantly". If
395 both mates have unique alignments, but the alignments do not match paired-end
396 expectations (i.e. the mates aren't in the expected relative orientation, or
397 aren't within the expected distance range, or both), the pair is said to align
398 "discordantly". Discordant alignments may be of particular interest, for
399 instance, when seeking [structural variants].
400
401 The expected relative orientation of the mates is set using the [`--ff`],
402 [`--fr`], or [`--rf`] options. The expected range of inter-mates distances (as
403 measured from the furthest extremes of the mates; also called "outer distance")
404 is set with the [`-I`][`+I`] and [`-X`][`+X`] options. Note that setting [`-I`][`+I`] and [`-X`][`+X`]
405 far apart makes Bowtie 2 slower. See documentation for [`-I`][`+I`] and [`-X`][`+X`].
406
407 To declare that a pair aligns discordantly, Bowtie 2 requires that both mates
408 align uniquely. This is a conservative threshold, but this is often desirable
409 when seeking structural variants.
410
411 By default, Bowtie 2 searches for both concordant and discordant alignments,
412 though searching for discordant alignments can be disabled with the
413 [`--no-discordant`] option.
414
415
416 ### Mixed mode: paired where possible, unpaired otherwise
417
418 If Bowtie 2 cannot find a paired-end alignment for a pair, by default it will go
419 on to look for unpaired alignments for the constituent mates. This is called
420 "mixed mode." To disable mixed mode, set the [`--no-mixed`] option.
421
422 Bowtie 2 runs a little faster in `--no-mixed` mode, but will only consider
423 alignment status of pairs per se, not individual mates.
424
425 ### Some SAM FLAGS describe paired-end properties
426
427 The SAM `FLAGS` field, the second field in a SAM record, has multiple bits that
428 describe the paired-end nature of the read and alignment. The first (least
429 significant) bit (1 in decimal, 0x1 in hexadecimal) is set if the read is part
430 of a pair. The second bit (2 in decimal, 0x2 in hexadecimal) is set if the read
431 is part of a pair that aligned in a paired-end fashion. The fourth bit (8 in
432 decimal, 0x8 in hexadecimal) is set if the read is part of a pair and the other
433 mate in the pair had at least one valid alignment. The sixth bit (32 in
434 decimal, 0x20 in hexadecimal) is set if the read is part of a pair and the other
435 mate in the pair aligned to the Crick strand (or, equivalently, if the reverse
436 complement of the other mate aligned to the Watson strand). The seventh bit (64
437 in decimal, 0x40 in hexadecimal) is set if the read is mate 1 in a pair. The
438 eighth bit (128 in decimal, 0x80 in hexadecimal) is set if the read is mate 2 in
439 a pair. See the [SAM specification] for a more detailed description of the
440 `FLAGS` field.
441
442 ### Some SAM optional fields describe more paired-end properties
443
444 The last several fields of each SAM record usually contain SAM optional fields,
445 which are simply tab-separated strings conveying additional information about
446 the reads and alignments. A SAM optional field is formatted like this: "XP:i:1"
447 where "XP" is the `TAG`, "i" is the `TYPE` ("integer" in this case), and "1" is
448 the `VALUE`. See the [SAM specification] for details regarding SAM optional
449 fields.
450
451 ### Mates can overlap, contain, or dovetail each other
452
453 The fragment and read lengths might be such that alignments for the two mates
454 from a pair overlap each other. Consider this example:
455
456 (For these examples, assume we expect mate 1 to align to the left of mate 2.)
457
458 Mate 1: GCAGATTATATGAGTCAGCTACGATATTGTT
459 Mate 2: TGTTTGGGGTGACACATTACGCGTCTTTGAC
460 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
461
462 It's also possible, though unusual, for one mate alignment to contain the other,
463 as in these examples:
464
465 Mate 1: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGC
466 Mate 2: TGTTTGGGGTGACACATTACGC
467 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
468
469 Mate 1: CAGCTACGATATTGTTTGGGGTGACACATTACGC
470 Mate 2: CTACGATATTGTTTGGGGTGAC
471 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
472
473 And it's also possible, though unusual, for the mates to "dovetail", with the
474 mates seemingly extending "past" each other as in this example:
475
476 Mate 1: GTCAGCTACGATATTGTTTGGGGTGACACATTACGC
477 Mate 2: TATGAGTCAGCTACGATATTGTTTGGGGTGACACAT
478 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
479
480 In some situations, it's desirable for the aligner to consider all these cases
481 as "concordant" as long as other paired-end constraints are not violated. Bowtie
482 2's default behavior is to consider overlapping and containing as being
483 consistent with concordant alignment. By default, dovetailing is considered
484 inconsistent with concordant alignment.
485
486 These defaults can be overridden. Setting [`--no-overlap`] causes Bowtie 2 to
487 consider overlapping mates as non-concordant. Setting [`--no-contain`] causes
488 Bowtie 2 to consider cases where one mate alignment contains the other as
489 non-concordant. Setting [`--dovetail`] causes Bowtie 2 to consider cases where
490 the mate alignments dovetail as concordant.
491
492 Reporting
493 ---------
494
495 The reporting mode governs how many alignments Bowtie 2 looks for, and how to
496 report them. Bowtie 2 has three distinct reporting modes. The default
497 reporting mode is similar to the default reporting mode of many other read
498 alignment tools, including [BWA]. It is also similar to Bowtie 1's `-M`
499 alignment mode.
500
501 In general, when we say that a read has an alignment, we mean that it has a
502 [valid alignment]. When we say that a read has multiple alignments, we mean
503 that it has multiple alignments that are valid and distinct from one another.
504
505
506 ### Distinct alignments map a read to different places
507
508 Two alignments for the same individual read are "distinct" if they map the same
509 read to different places. Specifically, we say that two alignments are distinct
510 if there are no alignment positions where a particular read offset is aligned
511 opposite a particular reference offset in both alignments with the same
512 orientation. E.g. if the first alignment is in the forward orientation and
513 aligns the read character at read offset 10 to the reference character at
514 chromosome 3, offset 3,445,245, and the second alignment is also in the forward
515 orientation and also aligns the read character at read offset 10 to the
516 reference character at chromosome 3, offset 3,445,245, they are not distinct
517 alignments.
518
519 Two alignments for the same pair are distinct if either the mate 1s in the two
520 paired-end alignments are distinct or the mate 2s in the two alignments are
521 distinct or both.
522
523 ### Default mode: search for multiple alignments, report the best one
524
525 By default, Bowtie 2 searches for distinct, valid alignments for each read. When
526 it finds a valid alignment, it generally will continue to look for alignments
527 that are nearly as good or better. It will eventually stop looking, either
528 because it exceeded a limit placed on search effort (see [`-D`] and [`-R`][`+R`]) or
529 because it already knows all it needs to know to report an alignment.
530 Information from the best alignments are used to estimate mapping quality (the
531 `MAPQ` [SAM] field) and to set SAM optional fields, such as [`AS:i`] and
532 [`XS:i`]. Bowtie 2 does not guarantee that the alignment reported is the best
533 possible in terms of alignment score.
534
535 See also: [`-D`], which puts an upper limit on the number of dynamic programming
536 problems (i.e. seed extensions) that can "fail" in a row before Bowtie 2 stops
537 searching. Increasing [`-D`] makes Bowtie 2 slower, but increases the
538 likelihood that it will report the correct alignment for a read that aligns many
539 places.
540
541 See also: [`-R`][`+R`], which sets the maximum number of times Bowtie 2 will "re-seed"
542 when attempting to align a read with repetitive seeds. Increasing [`-R`][`+R`] makes
543 Bowtie 2 slower, but increases the likelihood that it will report the correct
544 alignment for a read that aligns many places.
545
546 ### -k mode: search for one or more alignments, report each
547
548 In [`-k`] mode, Bowtie 2 searches for up to N distinct, valid alignments for
549 each read, where N equals the integer specified with the `-k` parameter. That
550 is, if `-k 2` is specified, Bowtie 2 will search for at most 2 distinct
551 alignments. It reports all alignments found, in descending order by alignment
552 score. The alignment score for a paired-end alignment equals the sum of the
553 alignment scores of the individual mates. Each reported read or pair alignment
554 beyond the first has the SAM 'secondary' bit (which equals 256) set in its FLAGS
555 field. Supplementary alignments will also be assigned a MAPQ of 255.
556 See the [SAM specification] for details.
557
558 Bowtie 2 does not "find" alignments in any specific order, so for reads that
559 have more than N distinct, valid alignments, Bowtie 2 does not guarantee that
560 the N alignments reported are the best possible in terms of alignment score.
561 Still, this mode can be effective and fast in situations where the user cares
562 more about whether a read aligns (or aligns a certain number of times) than
563 where exactly it originated.
564
565
566 ### -a mode: search for and report all alignments
567
568 [`-a`] mode is similar to [`-k`] mode except that there is no upper limit on the
569 number of alignments Bowtie 2 should report. Alignments are reported in
570 descending order by alignment score. The alignment score for a paired-end
571 alignment equals the sum of the alignment scores of the individual mates. Each
572 reported read or pair alignment beyond the first has the SAM 'secondary' bit
573 (which equals 256) set in its FLAGS field. Supplementary alignments will be assigned
574 a MAPQ of 255. See the [SAM specification] for details.
575
576 Some tools are designed with this reporting mode in mind. Bowtie 2 is not! For
577 very large genomes, this mode is very slow.
578
579
580 ### Randomness in Bowtie 2
581
582 Bowtie 2's search for alignments for a given read is "randomized." That is,
583 when Bowtie 2 encounters a set of equally-good choices, it uses a pseudo-random
584 number to choose. For example, if Bowtie 2 discovers a set of 3 equally-good
585 alignments and wants to decide which to report, it picks a pseudo-random integer
586 0, 1 or 2 and reports the corresponding alignment. Arbitrary choices can crop up
587 at various points during alignment.
588
589 The pseudo-random number generator is re-initialized for every read, and the
590 seed used to initialize it is a function of the read name, nucleotide string,
591 quality string, and the value specified with [`--seed`]. If you run the same
592 version of Bowtie 2 on two reads with identical names, nucleotide strings, and
593 quality strings, and if [`--seed`] is set the same for both runs, Bowtie 2 will
594 produce the same output; i.e., it will align the read to the same place, even if
595 there are multiple equally good alignments. This is intuitive and desirable in
596 most cases. Most users expect Bowtie to produce the same output when run twice
597 on the same input.
598
599 However, when the user specifies the [`--non-deterministic`] option, Bowtie 2
600 will use the current time to re-initialize the pseudo-random number generator.
601 When this is specified, Bowtie 2 might report different alignments for identical
602 reads. This is counter-intuitive for some users, but might be more appropriate
603 in situations where the input consists of many identical reads.
604
605 Multiseed heuristic
606 -------------------
607
608 To rapidly narrow the number of possible alignments that must be considered,
609 Bowtie 2 begins by extracting substrings ("seeds") from the read and its reverse
610 complement and aligning them in an ungapped fashion with the help of the [FM Index][FM Index Paper].
611 This is "multiseed alignment" and it is similar to what [Bowtie 1
612 does], except Bowtie 1 attempts to align the entire read this way.
613
614 This initial step makes Bowtie 2 much faster than it would be without such a
615 filter, but at the expense of missing some valid alignments. For instance, it
616 is possible for a read to have a valid overall alignment but to have no valid
617 seed alignments because each potential seed alignment is interrupted by too many
618 mismatches or gaps.
619
620 The trade-off between speed and sensitivity/accuracy can be adjusted by setting
621 the seed length ([`-L`]), the interval between extracted seeds ([`-i`]), and the
622 number of mismatches permitted per seed ([`-N`]). For more sensitive alignment,
623 set these parameters to (a) make the seeds closer together, (b) make the seeds
624 shorter, and/or (c) allow more mismatches. You can adjust these options
625 one-by-one, though Bowtie 2 comes with some useful combinations of options
626 prepackaged as "[preset options]."
627
628 [`-D`] and [`-R`][`+R`] are also options that adjust the trade-off between speed and
629 sensitivity/accuracy.
630
631
632 ### FM Index memory footprint
633
634 Bowtie 2 uses the [FM Index][FM Index Paper] to find ungapped alignments for seeds. This step
635 accounts for the bulk of Bowtie 2's memory footprint, as the [FM Index][FM Index Paper] itself
636 is typically the largest data structure used. For instance, the memory
637 footprint of the [FM Index][FM Index Paper] for the human genome is about 3.2 gigabytes of RAM.
638
639
640 Ambiguous characters
641 --------------------
642
643 Non-whitespace characters besides A, C, G or T are considered "ambiguous." N is
644 a common ambiguous character that appears in reference sequences. Bowtie 2
645 considers all ambiguous characters in the reference (including [IUPAC nucleotide
646 codes]) to be Ns.
647
648 Bowtie 2 allows alignments to overlap ambiguous characters in the reference. An
649 alignment position that contains an ambiguous character in the read, reference,
650 or both, is penalized according to [`--np`]. [`--n-ceil`] sets an upper limit
651 on the number of positions that may contain ambiguous reference characters in a
652 valid alignment. The optional field [`XN:i`] reports the number of ambiguous
653 reference characters overlapped by an alignment.
654
655 Note that the [multiseed heuristic] cannot find *seed* alignments that overlap
656 ambiguous reference characters. For an alignment overlapping an ambiguous
657 reference character to be found, it must have one or more seed alignments that
658 do not overlap ambiguous reference characters.
659
660
661 Presets: setting many settings at once
662 --------------------------------------
663
664 Bowtie 2 comes with some useful combinations of parameters packaged into shorter
665 "preset" parameters. For example, running Bowtie 2 with the [`--very-sensitive`]
666 option is the same as running with options: `-D 20 -R 3 -N 0 -L 20 -i S,1,0.50`.
667 The preset options that come with Bowtie 2 are designed to cover a wide area of
668 the speed/sensitivity/accuracy trade-off space, with the presets ending in `fast`
669 generally being faster but less sensitive and less accurate, and the presets
670 ending in `sensitive` generally being slower but more sensitive and more
671 accurate. See the [documentation for the preset options] for details.
672
673 As of Bowtie2 v2.4.0, individual preset values can be overridden by providing the
674 specific options e.g. the configured seed length of 20 in the [`--very-senitive`]
675 preset above can be changed to 25 by also specifying the `-L 25` parameter
676 anywhere on the command line.
677
678 Filtering
679 ---------
680
681 Some reads are skipped or "filtered out" by Bowtie 2. For example, reads may be
682 filtered out because they are extremely short or have a high proportion of
683 ambiguous nucleotides. Bowtie 2 will still print a SAM record for such a read,
684 but no alignment will be reported and the `YF:i` SAM optional field will be
685 set to indicate the reason the read was filtered.
686
687 * `YF:Z:LN`: the read was filtered because it had length less than or equal to
688 the number of seed mismatches set with the [`-N`] option.
689 * `YF:Z:NS`: the read was filtered because it contains a number of ambiguous
690 characters (usually `N` or `.`) greater than the ceiling specified with
691 [`--n-ceil`].
692 * `YF:Z:SC`: the read was filtered because the read length and the match bonus
693 (set with [`--ma`]) are such that the read can't possibly earn an alignment
694 score greater than or equal to the threshold set with [`--score-min`]
695 * `YF:Z:QC`: the read was filtered because it was marked as failing quality
696 control and the user specified the [`--qc-filter`] option. This only happens
697 when the input is in Illumina's QSEQ format (i.e. when [`--qseq`] is specified)
698 and the last (11th) field of the read's QSEQ record contains `1`.
699
700 If a read could be filtered for more than one reason, the value `YF:Z` flag will
701 reflect only one of those reasons.
702
703 Alignment summary
704 ------------------
705
706 When Bowtie 2 finishes running, it prints messages summarizing what happened.
707 These messages are printed to the "standard error" ("stderr") filehandle. For
708 datasets consisting of unpaired reads, the summary might look like this:
709
710 20000 reads; of these:
711 20000 (100.00%) were unpaired; of these:
712 1247 (6.24%) aligned 0 times
713 18739 (93.69%) aligned exactly 1 time
714 14 (0.07%) aligned >1 times
715 93.77% overall alignment rate
716
717 For datasets consisting of pairs, the summary might look like this:
718
719 10000 reads; of these:
720 10000 (100.00%) were paired; of these:
721 650 (6.50%) aligned concordantly 0 times
722 8823 (88.23%) aligned concordantly exactly 1 time
723 527 (5.27%) aligned concordantly >1 times
724 ----
725 650 pairs aligned concordantly 0 times; of these:
726 34 (5.23%) aligned discordantly 1 time
727 ----
728 616 pairs aligned 0 times concordantly or discordantly; of these:
729 1232 mates make up the pairs; of these:
730 660 (53.57%) aligned 0 times
731 571 (46.35%) aligned exactly 1 time
732 1 (0.08%) aligned >1 times
733 96.70% overall alignment rate
734
735 The indentation indicates how subtotals relate to totals.
736
737 Wrapper scripts
738 ---------------
739
740 The `bowtie2`, `bowtie2-build` and `bowtie2-inspect` executables are actually
741 wrapper scripts that call binary programs as appropriate. The wrappers shield
742 users from having to distinguish between "small" and "large" index formats,
743 discussed briefly in the following section. Also, the `bowtie2` wrapper
744 provides some key functionality, like the ability to handle compressed inputs,
745 and the functionality for [`--un`], [`--al`] and related options.
746
747 It is recommended that you always run the bowtie2 wrappers and not run the
748 binaries directly.
749
750 Small and large indexes
751 -----------------------
752
753 `bowtie2-build` can index reference genomes of any size. For genomes less than
754 about 4 billion nucleotides in length, `bowtie2-build` builds a "small" index
755 using 32-bit numbers in various parts of the index. When the genome is longer,
756 `bowtie2-build` builds a "large" index using 64-bit numbers. Small indexes are
757 stored in files with the `.bt2` extension, and large indexes are stored in
758 files with the `.bt2l` extension. The user need not worry about whether a
759 particular index is small or large; the wrapper scripts will automatically build
760 and use the appropriate index.
761
762 Performance tuning
763 ------------------
764
765 1. If your computer has multiple processors/cores, use `-p`
766
767 The [`-p`] option causes Bowtie 2 to launch a specified number of parallel
768 search threads. Each thread runs on a different processor/core and all
769 threads find alignments in parallel, increasing alignment throughput by
770 approximately a multiple of the number of threads (though in practice,
771 speedup is somewhat worse than linear).
772
773 2. If reporting many alignments per read, try reducing
774 `bowtie2-build --offrate`
775
776 If you are using [`-k`] or [`-a`] options and Bowtie 2 is reporting many
777 alignments per read, using an index with a denser SA sample can speed
778 things up considerably. To do this, specify a smaller-than-default
779 [`-o`/`--offrate`] value when running `bowtie2-build`.
780 A denser SA sample yields a larger index, but is also particularly
781 effective at speeding up alignment when many alignments are reported per
782 read.
783
784 3. If `bowtie2` "thrashes", try increasing `bowtie2-build --offrate`
785
786 If `bowtie2` runs very slowly on a relatively low-memory computer, try
787 setting [`-o`/`--offrate`] to a *larger* value when building the index.
788 This decreases the memory footprint of the index.
789
790 Command Line
791 ------------
792
793 ### Setting function options
794
795 Some Bowtie 2 options specify a function rather than an individual number or
796 setting. In these cases the user specifies three parameters: (a) a function
797 type `F`, (b) a constant term `B`, and (c) a coefficient `A`. The available
798 function types are constant (`C`), linear (`L`), square-root (`S`), and natural
799 log (`G`). The parameters are specified as `F,B,A` - that is, the function type,
800 the constant term, and the coefficient are separated by commas with no
801 whitespace. The constant term and coefficient may be negative and/or
802 floating-point numbers.
803
804 For example, if the function specification is `L,-0.4,-0.6`, then the function
805 defined is:
806
807 f(x) = -0.4 + -0.6 * x
808
809 If the function specification is `G,1,5.4`, then the function defined is:
810
811 f(x) = 1.0 + 5.4 * ln(x)
812
813 See the documentation for the option in question to learn what the parameter `x`
814 is for. For example, in the case if the [`--score-min`] option, the function
815 `f(x)` sets the minimum alignment score necessary for an alignment to be
816 considered valid, and `x` is the read length.
817
818 ### Usage
819
820 bowtie2 [options]* -x <bt2-idx> {-1 <m1> -2 <m2> | -U <r> | --interleaved <i> | --sra-acc <acc> | -b <bam>} -S [<sam>]
821
822 ### Main arguments
823
824 <table><tr><td id="bowtie2-options-x">
825
826 -x <bt2-idx>
827
828 </td><td>
829
830 The basename of the index for the reference genome. The basename is the name of
831 any of the index files up to but not including the final `.1.bt2` / `.rev.1.bt2`
832 / etc. `bowtie2` looks for the specified index first in the current directory,
833 then in the directory specified in the `BOWTIE2_INDEXES` environment variable.
834
835 </td></tr>
836 <tr><td id="bowtie2-options-1">
837
838 -1 <m1>
839
840 </td><td>
841
842 Comma-separated list of files containing mate 1s (filename usually includes
843 `_1`), e.g. `-1 flyA_1.fq,flyB_1.fq`. Sequences specified with this option must
844 correspond file-for-file and read-for-read with those specified in `<m2>`. Reads
845 may be a mix of different lengths. If `-` is specified, `bowtie2` will read the
846 mate 1s from the "standard in" or "stdin" filehandle.
847
848 </td></tr>
849 <tr><td id="bowtie2-options-2">
850
851 -2 <m2>
852
853 </td><td>
854
855 Comma-separated list of files containing mate 2s (filename usually includes
856 `_2`), e.g. `-2 flyA_2.fq,flyB_2.fq`. Sequences specified with this option must
857 correspond file-for-file and read-for-read with those specified in `<m1>`. Reads
858 may be a mix of different lengths. If `-` is specified, `bowtie2` will read the
859 mate 2s from the "standard in" or "stdin" filehandle.
860
861 </td></tr>
862 <tr><td id="bowtie2-options-U">
863
864 -U <r>
865
866 </td><td>
867
868 Comma-separated list of files containing unpaired reads to be aligned, e.g.
869 `lane1.fq,lane2.fq,lane3.fq,lane4.fq`. Reads may be a mix of different lengths.
870 If `-` is specified, `bowtie2` gets the reads from the "standard in" or "stdin"
871 filehandle.
872
873 </td></tr>
874 <tr><td id="bowtie2-options-interleaved">
875
876 --interleaved
877
878 </td><td>
879
880 Reads interleaved FASTQ files where the first two records (8 lines)
881 represent a mate pair.
882
883 </td></tr>
884 <tr><td id="bowtie2-options-sra-acc">
885
886 --sra-acc
887
888 </td><td>
889
890 Reads are SRA accessions. If the accession provided cannot be found in
891 local storage it will be fetched from the NCBI database. If you find that
892 SRA alignments are long running please rerun your command with the
893 [`-p`/`--threads`] parameter set to desired number of threads.
894
895 NB: this option is only available if bowtie 2 is compiled with the necessary
896 SRA libraries. See [Obtaining Bowtie 2][obtain Bowtie 2] for details.
897
898 </td></tr>
899 <tr><td id="bowtie2-options-b">
900
901 -b <bam>
902
903 </td><td>
904
905 Reads are unaligned BAM records sorted by read name.
906 The [`--align-paired-reads`] and [`--preserve-tags`] options
907 affect the way Bowtie 2 processes records.
908
909 </td></tr>
910 <tr><td id="bowtie2-options-S">
911
912 -S <sam>
913
914 </td><td>
915
916 File to write SAM alignments to. By default, alignments are written to the
917 "standard out" or "stdout" filehandle (i.e. the console).
918
919 </td></tr></table>
920
921 ### Options
922
923 #### Input options
924
925 <table>
926 <tr><td id="bowtie2-options-q">
927
928 -q
929
930 </td><td>
931
932 Reads (specified with `<m1>`, `<m2>`, `<s>`) are FASTQ files. FASTQ files
933 usually have extension `.fq` or `.fastq`. FASTQ is the default format. See
934 also: [`--solexa-quals`] and [`--int-quals`].
935
936 </td></tr>
937 <tr><td id="bowtie2-options-tab5">
938
939 --tab5
940
941 </td><td>
942
943 Each read or pair is on a single line. An unpaired read line is
944 `[name]\t[seq]\t[qual]\n`. A paired-end read line is
945 `[name]\t[seq1]\t[qual1]\t[seq2]\t[qual2]\n`. An input file can be a
946 mix of unpaired and paired-end reads and Bowtie 2 recognizes each
947 according to the number of fields, handling each as it should.
948
949 </td></tr>
950 <tr><td id="bowtie2-options-tab6">
951
952 --tab6
953
954 </td><td>
955
956 Similar to [`--tab5`] except, for paired-end reads, the second end can have a
957 different name from the first:
958 `[name1]\t[seq1]\t[qual1]\t[name2]\t[seq2]\t[qual2]\n`
959
960 </td></tr>
961 <tr><td id="bowtie2-options-qseq">
962
963 --qseq
964
965 </td><td>
966
967 Reads (specified with `<m1>`, `<m2>`, `<s>`) are QSEQ files. QSEQ files usually
968 end in `_qseq.txt`. See also: [`--solexa-quals`] and [`--int-quals`].
969
970 </td></tr>
971 <tr><td id="bowtie2-options-f">
972
973 -f
974
975 </td><td>
976
977 Reads (specified with `<m1>`, `<m2>`, `<s>`) are [`FASTA`] files. [`FASTA`] files
978 usually have extension `.fa`, `.fasta`, `.mfa`, `.fna` or similar. [`FASTA`] files
979 do not have a way of specifying quality values, so when `-f` is set, the result
980 is as if [`--ignore-quals`] is also set.
981
982 </td></tr>
983 <tr><td id="bowtie2-options-r">
984
985 -r
986
987 </td><td>
988
989 Reads (specified with `<m1>`, `<m2>`, `<s>`) are files with one input sequence
990 per line, without any other information (no read names, no qualities). When
991 `-r` is set, the result is as if [`--ignore-quals`] is also set.
992
993 </td></tr>
994 <tr><td id="bowtie2-options-F">
995
996 -F k:<int>,i:<int>
997
998 </td><td>
999
1000 Reads are substrings (k-mers) extracted from a FASTA file.
1001 Specifically, for every reference sequence in the FASTA file, Bowtie
1002 2 aligns the k-mers at offsets 1, 1+i, 1+2i, ... until reaching the
1003 end of the reference. Each k-mer is aligned as a separate read.
1004 Quality values are set to all Is (40 on Phred scale). Each k-mer
1005 (read) is given a name like `<sequence>_<offset>`, where `<sequence>`
1006 is the name of the FASTA sequence it was drawn from and `<offset>`
1007 is its 0-based offset of origin with respect to the sequence. Only
1008 single k-mers, i.e. unpaired reads, can be aligned in this way.
1009 </td></tr>
1010 <tr><td id="bowtie2-options-c">
1011
1012 -c
1013
1014 </td><td>
1015
1016 The read sequences are given on command line. I.e. `<m1>`, `<m2>` and
1017 `<singles>` are comma-separated lists of reads rather than lists of read files.
1018 There is no way to specify read names or qualities, so `-c` also implies
1019 [`--ignore-quals`].
1020
1021 </td></tr>
1022 <tr><td id="bowtie2-options-s">
1023
1024 -s/--skip <int>
1025
1026 </td><td>
1027
1028 Skip (i.e. do not align) the first `<int>` reads or pairs in the input.
1029
1030 </td></tr>
1031 <tr><td id="bowtie2-options-u">
1032
1033 -u/--qupto <int>
1034
1035 </td><td>
1036
1037 Align the first `<int>` reads or read pairs from the input (after the
1038 [`-s`/`--skip`] reads or pairs have been skipped), then stop. Default: no limit.
1039
1040 </td></tr>
1041 <tr><td id="bowtie2-options-5">
1042
1043 -5/--trim5 <int>
1044
1045 </td><td>
1046
1047 Trim `<int>` bases from 5' (left) end of each read before alignment (default: 0).
1048
1049 </td></tr>
1050 <tr><td id="bowtie2-options-3">
1051
1052 -3/--trim3 <int>
1053
1054 </td><td>
1055
1056 Trim `<int>` bases from 3' (right) end of each read before alignment (default: 0).
1057
1058 </td></tr><tr><td id="bowtie2-options-trim-to">
1059
1060 --trim-to [3:|5:]<int>
1061
1062 </td><td>
1063
1064 Trim reads exceeding `<int>` bases. Bases will be trimmed from either the 3' (right)
1065 or 5' (left) end of the read. If the read end if not specified, bowtie 2 will default
1066 to trimming from the 3' (right) end of the read. [`--trim-to`] and [`-3`]/[`-5`] are
1067 mutually exclusive.
1068
1069 </td></tr><tr><td id="bowtie2-options-phred33-quals">
1070
1071 --phred33
1072
1073 </td><td>
1074
1075 Input qualities are ASCII chars equal to the [Phred quality] plus 33. This is
1076 also called the "Phred+33" encoding, which is used by the very latest Illumina
1077 pipelines.
1078
1079 </td></tr>
1080 <tr><td id="bowtie2-options-phred64-quals">
1081
1082 --phred64
1083
1084 </td><td>
1085
1086 Input qualities are ASCII chars equal to the [Phred quality] plus 64. This is
1087 also called the "Phred+64" encoding.
1088
1089 </td></tr>
1090 <tr><td id="bowtie2-options-solexa-quals">
1091
1092 --solexa-quals
1093
1094 </td><td>
1095
1096 Convert input qualities from [Solexa][Phred quality] (which can be negative) to
1097 [Phred][Phred quality] (which can't). This scheme was used in older Illumina GA
1098 Pipeline versions (prior to 1.3). Default: off.
1099
1100 </td></tr>
1101 <tr><td id="bowtie2-options-int-quals">
1102
1103 --int-quals
1104
1105 </td><td>
1106
1107 Quality values are represented in the read input file as space-separated ASCII
1108 integers, e.g., `40 40 30 40`..., rather than ASCII characters, e.g., `II?I`....
1109 Integers are treated as being on the [Phred quality] scale unless
1110 [`--solexa-quals`] is also specified. Default: off.
1111
1112 </td></tr></table>
1113
1114 #### Preset options in `--end-to-end` mode
1115
1116 <table>
1117 <tr><td id="bowtie2-options-very-fast">
1118
1119 --very-fast
1120
1121 </td><td>
1122
1123 Same as: `-D 5 -R 1 -N 0 -L 22 -i S,0,2.50`
1124
1125 </td></tr>
1126 <tr><td id="bowtie2-options-fast">
1127
1128 --fast
1129
1130 </td><td>
1131
1132 Same as: `-D 10 -R 2 -N 0 -L 22 -i S,0,2.50`
1133
1134 </td></tr>
1135 <tr><td id="bowtie2-options-sensitive">
1136
1137 --sensitive
1138
1139 </td><td>
1140
1141 Same as: `-D 15 -R 2 -N 0 -L 22 -i S,1,1.15` (default in [`--end-to-end`] mode)
1142
1143 </td></tr>
1144 <tr><td id="bowtie2-options-very-sensitive">
1145
1146 --very-sensitive
1147
1148 </td><td>
1149
1150 Same as: `-D 20 -R 3 -N 0 -L 20 -i S,1,0.50`
1151
1152 </td></tr>
1153 </table>
1154
1155 #### Preset options in `--local` mode
1156
1157 <table>
1158 <tr><td id="bowtie2-options-very-fast-local">
1159
1160 --very-fast-local
1161
1162 </td><td>
1163
1164 Same as: `-D 5 -R 1 -N 0 -L 25 -i S,1,2.00`
1165
1166 </td></tr>
1167 <tr><td id="bowtie2-options-fast-local">
1168
1169 --fast-local
1170
1171 </td><td>
1172
1173 Same as: `-D 10 -R 2 -N 0 -L 22 -i S,1,1.75`
1174
1175 </td></tr>
1176 <tr><td id="bowtie2-options-sensitive-local">
1177
1178 --sensitive-local
1179
1180 </td><td>
1181
1182 Same as: `-D 15 -R 2 -N 0 -L 20 -i S,1,0.75` (default in [`--local`] mode)
1183
1184 </td></tr>
1185 <tr><td id="bowtie2-options-very-sensitive-local">
1186
1187 --very-sensitive-local
1188
1189 </td><td>
1190
1191 Same as: `-D 20 -R 3 -N 0 -L 20 -i S,1,0.50`
1192
1193 </td></tr>
1194 </table>
1195
1196 #### Alignment options
1197
1198 <table>
1199
1200 <tr><td id="bowtie2-options-N">
1201
1202 -N <int>
1203
1204 </td><td>
1205
1206 Sets the number of mismatches to allowed in a seed alignment during [multiseed
1207 alignment]. Can be set to 0 or 1. Setting this higher makes alignment slower
1208 (often much slower) but increases sensitivity. Default: 0.
1209
1210 </td></tr>
1211 <tr><td id="bowtie2-options-L">
1212
1213 -L <int>
1214
1215 </td><td>
1216
1217 Sets the length of the seed substrings to align during [multiseed alignment].
1218 Smaller values make alignment slower but more sensitive. Default: the
1219 [`--sensitive`] preset is used by default, which sets `-L` to 22 and
1220 20 in [`--end-to-end`] mode and in [`--local`] mode.
1221
1222 </td></tr>
1223 <tr><td id="bowtie2-options-i">
1224
1225 -i <func>
1226
1227 </td><td>
1228
1229 Sets a function governing the interval between seed substrings to use during
1230 [multiseed alignment]. For instance, if the read has 30 characters, and seed
1231 length is 10, and the seed interval is 6, the seeds extracted will be:
1232
1233 Read: TAGCTACGCTCTACGCTATCATGCATAAAC
1234 Seed 1 fw: TAGCTACGCT
1235 Seed 1 rc: AGCGTAGCTA
1236 Seed 2 fw: CGCTCTACGC
1237 Seed 2 rc: GCGTAGAGCG
1238 Seed 3 fw: ACGCTATCAT
1239 Seed 3 rc: ATGATAGCGT
1240 Seed 4 fw: TCATGCATAA
1241 Seed 4 rc: TTATGCATGA
1242
1243 Since it's best to use longer intervals for longer reads, this parameter sets
1244 the interval as a function of the read length, rather than a single
1245 one-size-fits-all number. For instance, specifying `-i S,1,2.5` sets the
1246 interval function `f` to `f(x) = 1 + 2.5 * sqrt(x)`, where x is the read length.
1247 See also: [setting function options]. If the function returns a result less than
1248 1, it is rounded up to 1. Default: the [`--sensitive`] preset is used by
1249 default, which sets `-i` to `S,1,1.15` in [`--end-to-end`] mode to `-i S,1,0.75`
1250 in [`--local`] mode.
1251
1252 </td></tr>
1253 <tr><td id="bowtie2-options-n-ceil">
1254
1255 --n-ceil <func>
1256
1257 </td><td>
1258
1259 Sets a function governing the maximum number of ambiguous characters (usually
1260 `N`s and/or `.`s) allowed in a read as a function of read length. For instance,
1261 specifying `-L,0,0.15` sets the N-ceiling function `f` to `f(x) = 0 + 0.15 * x`,
1262 where x is the read length. See also: [setting function options]. Reads
1263 exceeding this ceiling are [filtered out]. Default: `L,0,0.15`.
1264
1265 </td></tr>
1266 <tr><td id="bowtie2-options-dpad">
1267
1268 --dpad <int>
1269
1270 </td><td>
1271
1272 "Pads" dynamic programming problems by `<int>` columns on either side to allow
1273 gaps. Default: 15.
1274
1275 </td></tr>
1276 <tr><td id="bowtie2-options-gbar">
1277
1278 --gbar <int>
1279
1280 </td><td>
1281
1282 Disallow gaps within `<int>` positions of the beginning or end of the read.
1283 Default: 4.
1284
1285 </td></tr>
1286 <tr><td id="bowtie2-options-ignore-quals">
1287
1288 --ignore-quals
1289
1290 </td><td>
1291
1292 When calculating a mismatch penalty, always consider the quality value at the
1293 mismatched position to be the highest possible, regardless of the actual value.
1294 I.e. input is treated as though all quality values are high. This is also the
1295 default behavior when the input doesn't specify quality values (e.g. in [`-f`],
1296 [`-r`], or [`-c`] modes).
1297
1298 </td></tr>
1299 <tr><td id="bowtie2-options-nofw">
1300
1301 --nofw/--norc
1302
1303 </td><td>
1304
1305 If `--nofw` is specified, `bowtie2` will not attempt to align unpaired reads to
1306 the forward (Watson) reference strand. If `--norc` is specified, `bowtie2` will
1307 not attempt to align unpaired reads against the reverse-complement (Crick)
1308 reference strand. In paired-end mode, `--nofw` and `--norc` pertain to the
1309 fragments; i.e. specifying `--nofw` causes `bowtie2` to explore only those
1310 paired-end configurations corresponding to fragments from the reverse-complement
1311 (Crick) strand. Default: both strands enabled.
1312
1313 </td></tr>
1314 <tr><td id="bowtie2-options-no-1mm-upfront">
1315
1316 --no-1mm-upfront
1317
1318 </td><td>
1319
1320 By default, Bowtie 2 will attempt to find either an exact or a 1-mismatch
1321 end-to-end alignment for the read *before* trying the [multiseed heuristic]. Such
1322 alignments can be found very quickly, and many short read alignments have exact or
1323 near-exact end-to-end alignments. However, this can lead to unexpected
1324 alignments when the user also sets options governing the [multiseed heuristic],
1325 like [`-L`] and [`-N`]. For instance, if the user specifies `-N 0` and `-L` equal
1326 to the length of the read, the user will be surprised to find 1-mismatch alignments
1327 reported. This option prevents Bowtie 2 from searching for 1-mismatch end-to-end
1328 alignments before using the [multiseed heuristic], which leads to the expected
1329 behavior when combined with options such as [`-L`] and [`-N`]. This comes at the
1330 expense of speed.
1331
1332 </td></tr><tr><td id="bowtie2-options-end-to-end">
1333
1334 --end-to-end
1335
1336 </td><td>
1337
1338 In this mode, Bowtie 2 requires that the entire read align from one end to the
1339 other, without any trimming (or "soft clipping") of characters from either end.
1340 The match bonus [`--ma`] always equals 0 in this mode, so all alignment scores
1341 are less than or equal to 0, and the greatest possible alignment score is 0.
1342 This is mutually exclusive with [`--local`]. `--end-to-end` is the default mode.
1343
1344 </td></tr>
1345 <tr><td id="bowtie2-options-local">
1346
1347 --local
1348
1349 </td><td>
1350
1351 In this mode, Bowtie 2 does not require that the entire read align from one end
1352 to the other. Rather, some characters may be omitted ("soft clipped") from the
1353 ends in order to achieve the greatest possible alignment score. The match bonus
1354 [`--ma`] is used in this mode, and the best possible alignment score is equal to
1355 the match bonus ([`--ma`]) times the length of the read. Specifying `--local`
1356 and one of the presets (e.g. `--local --very-fast`) is equivalent to specifying
1357 the local version of the preset (`--very-fast-local`). This is mutually
1358 exclusive with [`--end-to-end`]. `--end-to-end` is the default mode.
1359
1360 </td></tr>
1361 </table>
1362
1363 #### Scoring options
1364
1365 <table>
1366
1367 <tr><td id="bowtie2-options-ma">
1368
1369 --ma <int>
1370
1371 </td><td>
1372
1373 Sets the match bonus. In [`--local`] mode `<int>` is added to the alignment
1374 score for each position where a read character aligns to a reference character
1375 and the characters match. Not used in [`--end-to-end`] mode. Default: 2.
1376
1377 </td></tr>
1378 <tr><td id="bowtie2-options-mp">
1379
1380 --mp MX,MN
1381
1382 </td><td>
1383
1384 Sets the maximum (`MX`) and minimum (`MN`) mismatch penalties, both integers. A
1385 number less than or equal to `MX` and greater than or equal to `MN` is
1386 subtracted from the alignment score for each position where a read character
1387 aligns to a reference character, the characters do not match, and neither is an
1388 `N`. If [`--ignore-quals`] is specified, the number subtracted quals `MX`.
1389 Otherwise, the number subtracted is `MN + floor( (MX-MN)(MIN(Q, 40.0)/40.0) )`
1390 where Q is the Phred quality value. Default: `MX` = 6, `MN` = 2.
1391
1392 </td></tr>
1393 <tr><td id="bowtie2-options-np">
1394
1395 --np <int>
1396
1397 </td><td>
1398
1399 Sets penalty for positions where the read, reference, or both, contain an
1400 ambiguous character such as `N`. Default: 1.
1401
1402 </td></tr>
1403 <tr><td id="bowtie2-options-rdg">
1404
1405 --rdg <int1>,<int2>
1406
1407 </td><td>
1408
1409 Sets the read gap open (`<int1>`) and extend (`<int2>`) penalties. A read gap of
1410 length N gets a penalty of `<int1>` + N * `<int2>`. Default: 5, 3.
1411
1412 </td></tr>
1413 <tr><td id="bowtie2-options-rfg">
1414
1415 --rfg <int1>,<int2>
1416
1417 </td><td>
1418
1419 Sets the reference gap open (`<int1>`) and extend (`<int2>`) penalties. A
1420 reference gap of length N gets a penalty of `<int1>` + N * `<int2>`. Default:
1421 5, 3.
1422
1423 </td></tr>
1424 <tr><td id="bowtie2-options-score-min">
1425
1426 --score-min <func>
1427
1428 </td><td>
1429
1430 Sets a function governing the minimum alignment score needed for an alignment to
1431 be considered "valid" (i.e. good enough to report). This is a function of read
1432 length. For instance, specifying `L,0,-0.6` sets the minimum-score function `f`
1433 to `f(x) = 0 + -0.6 * x`, where `x` is the read length. See also: [setting
1434 function options]. The default in [`--end-to-end`] mode is `L,-0.6,-0.6` and
1435 the default in [`--local`] mode is `G,20,8`.
1436
1437 </td></tr>
1438 </table>
1439
1440 #### Reporting options
1441
1442 <table>
1443
1444 <tr><td id="bowtie2-options-k">
1445
1446 -k <int>
1447
1448 </td><td>
1449
1450 By default, `bowtie2` searches for distinct, valid alignments for each read.
1451 When it finds a valid alignment, it continues looking for alignments that are
1452 nearly as good or better. The best alignment found is reported (randomly
1453 selected from among best if tied). Information about the best alignments is
1454 used to estimate mapping quality and to set SAM optional fields, such as
1455 [`AS:i`] and [`XS:i`].
1456
1457 When `-k` is specified, however, `bowtie2` behaves differently. Instead, it
1458 searches for at most `<int>` distinct, valid alignments for each read. The
1459 search terminates when it can't find more distinct valid alignments, or when it
1460 finds `<int>`, whichever happens first. All alignments found are reported in
1461 descending order by alignment score. The alignment score for a paired-end
1462 alignment equals the sum of the alignment scores of the individual mates. Each
1463 reported read or pair alignment beyond the first has the SAM 'secondary' bit
1464 (which equals 256) set in its FLAGS field. For reads that have more than
1465 `<int>` distinct, valid alignments, `bowtie2` does not guarantee that the
1466 `<int>` alignments reported are the best possible in terms of alignment score.
1467 `-k` is mutually exclusive with [`-a`].
1468
1469 Note: Bowtie 2 is not designed with large values for `-k` in mind, and when
1470 aligning reads to long, repetitive genomes large `-k` can be very, very slow.
1471
1472 </td></tr>
1473 <tr><td id="bowtie2-options-a">
1474
1475 -a
1476
1477 </td><td>
1478
1479 Like [`-k`] but with no upper limit on number of alignments to search for. `-a`
1480 is mutually exclusive with [`-k`].
1481
1482 Note: Bowtie 2 is not designed with `-a` mode in mind, and when
1483 aligning reads to long, repetitive genomes this mode can be very, very slow.
1484
1485 </td></tr>
1486 </table>
1487
1488 #### Effort options
1489
1490 <table>
1491
1492 <tr><td id="bowtie2-options-D">
1493
1494 -D <int>
1495
1496 </td><td>
1497
1498 Up to `<int>` consecutive seed extension attempts can "fail" before Bowtie 2
1499 moves on, using the alignments found so far. A seed extension "fails" if it
1500 does not yield a new best or a new second-best alignment. This limit is
1501 automatically adjusted up when -k or -a are specified. Default: 15.
1502
1503 </td></tr>
1504 <tr><td id="bowtie2-options-R">
1505
1506 -R <int>
1507
1508 </td><td>
1509
1510 `<int>` is the maximum number of times Bowtie 2 will "re-seed" reads with
1511 repetitive seeds. When "re-seeding," Bowtie 2 simply chooses a new set of reads
1512 (same length, same number of mismatches allowed) at different offsets and
1513 searches for more alignments. A read is considered to have repetitive seeds if
1514 the total number of seed hits divided by the number of seeds that aligned at
1515 least once is greater than 300. Default: 2.
1516
1517 </td></tr>
1518 <tr><td id="bowtie2-options-d">
1519
1520 -d/--deterministic-seeds
1521
1522 </td><td>
1523
1524 Consider all seeds in order (no subsampling). Can be used to augment
1525 [`-a`] or [`-k`] with deterministic behavior. This option
1526 significantly speeds up [`-a`] while also reducing memory consumption.
1527 It is not however always strictly better than standalone `[-a]` when
1528 considering the number of repeated alignments found.
1529
1530 Note: In order to use this option exact upfront and 1mm upfront behavior
1531 have to be disabled using the following options: [`--no-exact-upfront`]
1532 and [`--no-1mm-upfront`].
1533
1534 </td></tr>
1535 </table>
1536
1537 #### Paired-end options
1538
1539 <table>
1540
1541 <tr><td id="bowtie2-options-I">
1542
1543 -I/--minins <int>
1544
1545 </td><td>
1546
1547 The minimum fragment length for valid paired-end alignments. E.g. if `-I 60` is
1548 specified and a paired-end alignment consists of two 20-bp alignments in the
1549 appropriate orientation with a 20-bp gap between them, that alignment is
1550 considered valid (as long as [`-X`][`+X`] is also satisfied). A 19-bp gap would not
1551 be valid in that case. If trimming options [`-3`] or [`-5`] are also used, the
1552 [`-I`][`+I`] constraint is applied with respect to the untrimmed mates.
1553
1554 The larger the difference between [`-I`][`+I`] and [`-X`][`+X`], the slower Bowtie 2 will
1555 run. This is because larger differences between [`-I`][`+I`] and [`-X`][`+X`] require that
1556 Bowtie 2 scan a larger window to determine if a concordant alignment exists.
1557 For typical fragment length ranges (200 to 400 nucleotides), Bowtie 2 is very
1558 efficient.
1559
1560 Default: 0 (essentially imposing no minimum)
1561
1562 </td></tr>
1563 <tr><td id="bowtie2-options-X">
1564
1565 -X/--maxins <int>
1566
1567 </td><td>
1568
1569 The maximum fragment length for valid paired-end alignments. E.g. if `-X 100`
1570 is specified and a paired-end alignment consists of two 20-bp alignments in the
1571 proper orientation with a 60-bp gap between them, that alignment is considered
1572 valid (as long as [`-I`][`+I`] is also satisfied). A 61-bp gap would not be valid in
1573 that case. If trimming options [`-3`] or [`-5`] are also used, the `-X`
1574 constraint is applied with respect to the untrimmed mates, not the trimmed
1575 mates.
1576
1577 The larger the difference between [`-I`][`+I`] and [`-X`][`+X`], the slower Bowtie 2 will
1578 run. This is because larger differences between [`-I`][`+I`] and [`-X`][`+X`] require that
1579 Bowtie 2 scan a larger window to determine if a concordant alignment exists.
1580 For typical fragment length ranges (200 to 400 nucleotides), Bowtie 2 is very
1581 efficient.
1582
1583 Default: 500.
1584
1585 </td></tr>
1586 <tr><td id="bowtie2-options-fr">
1587
1588 --fr/--rf/--ff
1589
1590 </td><td>
1591
1592 The upstream/downstream mate orientations for a valid paired-end alignment
1593 against the forward reference strand. E.g., if `--fr` is specified and there is
1594 a candidate paired-end alignment where mate 1 appears upstream of the reverse
1595 complement of mate 2 and the fragment length constraints ([`-I`][`+I`] and [`-X`][`+X`]) are
1596 met, that alignment is valid. Also, if mate 2 appears upstream of the reverse
1597 complement of mate 1 and all other constraints are met, that too is valid.
1598 `--rf` likewise requires that an upstream mate1 be reverse-complemented and a
1599 downstream mate2 be forward-oriented. ` --ff` requires both an upstream mate 1
1600 and a downstream mate 2 to be forward-oriented. Default: `--fr` (appropriate
1601 for Illumina's Paired-end Sequencing Assay).
1602
1603 </td></tr>
1604 <tr><td id="bowtie2-options-no-mixed">
1605
1606 --no-mixed
1607
1608 </td><td>
1609
1610 By default, when `bowtie2` cannot find a concordant or discordant alignment for
1611 a pair, it then tries to find alignments for the individual mates. This option
1612 disables that behavior.
1613
1614 </td></tr>
1615 <tr><td id="bowtie2-options-no-discordant">
1616
1617 --no-discordant
1618
1619 </td><td>
1620
1621 By default, `bowtie2` looks for discordant alignments if it cannot find any
1622 concordant alignments. A discordant alignment is an alignment where both mates
1623 align uniquely, but that does not satisfy the paired-end constraints
1624 ([`--fr`/`--rf`/`--ff`], [`-I`][`+I`], [`-X`][`+X`]). This option disables that behavior.
1625
1626 </td></tr>
1627 <tr><td id="bowtie2-options-dovetail">
1628
1629 --dovetail
1630
1631 </td><td>
1632
1633 If the mates "dovetail", that is if one mate alignment extends past the
1634 beginning of the other such that the wrong mate begins upstream, consider that
1635 to be concordant. See also: [Mates can overlap, contain or dovetail each
1636 other]. Default: mates cannot dovetail in a concordant alignment.
1637
1638 </td></tr>
1639 <tr><td id="bowtie2-options-no-contain">
1640
1641 --no-contain
1642
1643 </td><td>
1644
1645 If one mate alignment contains the other, consider that to be non-concordant.
1646 See also: [Mates can overlap, contain or dovetail each other]. Default: a mate
1647 can contain the other in a concordant alignment.
1648
1649 </td></tr>
1650 <tr><td id="bowtie2-options-no-overlap">
1651
1652 --no-overlap
1653
1654 </td><td>
1655
1656 If one mate alignment overlaps the other at all, consider that to be
1657 non-concordant. See also: [Mates can overlap, contain or dovetail each other].
1658 Default: mates can overlap in a concordant alignment.
1659
1660 </td></tr></table>
1661
1662 #### BAM options
1663
1664 <table>
1665
1666 <tr><td id="bowtie2-options-align-paired-reads">
1667
1668 --align-paired-reads
1669
1670 </td><td>
1671
1672 Bowtie 2 will, by default, attempt to align unpaired BAM reads.
1673 Use this option to align paired-end reads instead.
1674
1675 </td></tr>
1676 <tr><td id="bowtie2-options-preserve-tags">
1677
1678 --preserve-tags
1679
1680 </td><td>
1681
1682 Preserve tags from the original BAM record by appending them to the end
1683 of the corresponding Bowtie 2 SAM output.
1684
1685 </td></tr></table>
1686
1687 #### Output options
1688
1689 <table>
1690
1691 <tr><td id="bowtie2-options-t">
1692
1693 -t/--time
1694
1695 </td><td>
1696
1697 Print the wall-clock time required to load the index files and align the reads.
1698 This is printed to the "standard error" ("stderr") filehandle. Default: off.
1699
1700 </td></tr>
1701 <tr><td id="bowtie2-options-un">
1702
1703 --un <path>
1704 --un-gz <path>
1705 --un-bz2 <path>
1706 --un-lz4 <path>
1707
1708 </td><td>
1709
1710 Write unpaired reads that fail to align to file at `<path>`. These reads
1711 correspond to the SAM records with the FLAGS `0x4` bit set and neither the
1712 `0x40` nor `0x80` bits set. If `--un-gz` is specified, output will be gzip
1713 compressed. If `--un-bz2` or `--un-lz4` is specified, output will be bzip2 or
1714 lz4 compressed. Reads written in this way will appear exactly as they did in
1715 the input file, without any modification (same sequence, same name, same quality
1716 string, same quality encoding). Reads will not necessarily appear in the same
1717 order as they did in the input.
1718
1719 </td></tr>
1720 <tr><td id="bowtie2-options-al">
1721
1722 --al <path>
1723 --al-gz <path>
1724 --al-bz2 <path>
1725 --al-lz4 <path>
1726
1727 </td><td>
1728
1729 Write unpaired reads that align at least once to file at `<path>`. These reads
1730 correspond to the SAM records with the FLAGS `0x4`, `0x40`, and `0x80` bits
1731 unset. If `--al-gz` is specified, output will be gzip compressed. If `--al-bz2`
1732 is specified, output will be bzip2 compressed. Similarly if `--al-lz4` is specified,
1733 output will be lz4 compressed. Reads written in this way will
1734 appear exactly as they did in the input file, without any modification (same
1735 sequence, same name, same quality string, same quality encoding). Reads will
1736 not necessarily appear in the same order as they did in the input.
1737
1738 </td></tr>
1739 <tr><td id="bowtie2-options-un-conc">
1740
1741 --un-conc <path>
1742 --un-conc-gz <path>
1743 --un-conc-bz2 <path>
1744 --un-conc-lz4 <path>
1745
1746 </td><td>
1747
1748 Write paired-end reads that fail to align concordantly to file(s) at `<path>`.
1749 These reads correspond to the SAM records with the FLAGS `0x4` bit set and
1750 either the `0x40` or `0x80` bit set (depending on whether it's mate #1 or #2).
1751 `.1` and `.2` strings are added to the filename to distinguish which file
1752 contains mate #1 and mate #2. If a percent symbol, `%`, is used in `<path>`,
1753 the percent symbol is replaced with `1` or `2` to make the per-mate filenames.
1754 Otherwise, `.1` or `.2` are added before the final dot in `<path>` to make the
1755 per-mate filenames. Reads written in this way will appear exactly as they did
1756 in the input files, without any modification (same sequence, same name, same
1757 quality string, same quality encoding). Reads will not necessarily appear in
1758 the same order as they did in the inputs.
1759
1760 </td></tr>
1761 <tr><td id="bowtie2-options-al-conc">
1762
1763 --al-conc <path>
1764 --al-conc-gz <path>
1765 --al-conc-bz2 <path>
1766 --al-conc-lz4 <path>
1767
1768 </td><td>
1769
1770 Write paired-end reads that align concordantly at least once to file(s) at
1771 `<path>`. These reads correspond to the SAM records with the FLAGS `0x4` bit
1772 unset and either the `0x40` or `0x80` bit set (depending on whether it's mate #1
1773 or #2). `.1` and `.2` strings are added to the filename to distinguish which
1774 file contains mate #1 and mate #2. If a percent symbol, `%`, is used in
1775 `<path>`, the percent symbol is replaced with `1` or `2` to make the per-mate
1776 filenames. Otherwise, `.1` or `.2` are added before the final dot in `<path>` to
1777 make the per-mate filenames. Reads written in this way will appear exactly as
1778 they did in the input files, without any modification (same sequence, same name,
1779 same quality string, same quality encoding). Reads will not necessarily appear
1780 in the same order as they did in the inputs.
1781
1782 </td></tr>
1783 <tr><td id="bowtie2-options-quiet">
1784
1785 --quiet
1786
1787 </td><td>
1788
1789 Print nothing besides alignments and serious errors.
1790
1791 </td></tr>
1792 <tr><td id="bowtie2-options-met-file">
1793
1794 --met-file <path>
1795
1796 </td><td>
1797
1798 Write `bowtie2` metrics to file `<path>`. Having alignment metric can be useful
1799 for debugging certain problems, especially performance issues. See also:
1800 [`--met`]. Default: metrics disabled.
1801
1802 </td></tr>
1803 <tr><td id="bowtie2-options-met-stderr">
1804
1805 --met-stderr <path>
1806
1807 </td><td>
1808
1809 Write `bowtie2` metrics to the "standard error" ("stderr") filehandle. This is
1810 not mutually exclusive with [`--met-file`]. Having alignment metric can be
1811 useful for debugging certain problems, especially performance issues. See also:
1812 [`--met`]. Default: metrics disabled.
1813
1814 </td></tr>
1815 <tr><td id="bowtie2-options-met">
1816
1817 --met <int>
1818
1819 </td><td>
1820
1821 Write a new `bowtie2` metrics record every `<int>` seconds. Only matters if
1822 either [`--met-stderr`] or [`--met-file`] are specified. Default: 1.
1823
1824 </td></tr>
1825 </table>
1826
1827 #### SAM options
1828
1829 <table>
1830
1831 <tr><td id="bowtie2-options-no-unal">
1832
1833 --no-unal
1834
1835 </td><td>
1836
1837 Suppress SAM records for reads that failed to align.
1838
1839 </td></tr>
1840 <tr><td id="bowtie2-options-no-hd">
1841
1842 --no-hd
1843
1844 </td><td>
1845
1846 Suppress SAM header lines (starting with `@`).
1847
1848 </td></tr>
1849 <tr><td id="bowtie2-options-no-sq">
1850
1851 --no-sq
1852
1853 </td><td>
1854
1855 Suppress `@SQ` SAM header lines.
1856
1857 </td></tr>
1858 <tr><td id="bowtie2-options-rg-id">
1859
1860 --rg-id <text>
1861
1862 </td><td>
1863
1864 Set the read group ID to `<text>`. This causes the SAM `@RG` header line to be
1865 printed, with `<text>` as the value associated with the `ID:` tag. It also
1866 causes the `RG:Z:` extra field to be attached to each SAM output record, with
1867 value set to `<text>`.
1868
1869 </td></tr>
1870 <tr><td id="bowtie2-options-rg">
1871
1872 --rg <text>
1873
1874 </td><td>
1875
1876 Add `<text>` (usually of the form `TAG:VAL`, e.g. `SM:Pool1`) as a field on the
1877 `@RG` header line. Note: in order for the `@RG` line to appear, [`--rg-id`]
1878 must also be specified. This is because the `ID` tag is required by the [SAM
1879 Spec][SAM]. Specify `--rg` multiple times to set multiple fields. See the
1880 [SAM Spec][SAM] for details about what fields are legal.
1881
1882 </td></tr>
1883 <tr><td id="bowtie2-options-omit-sec-seq">
1884
1885 --omit-sec-seq
1886
1887 </td><td>
1888
1889 When printing secondary alignments, Bowtie 2 by default will write out the `SEQ`
1890 and `QUAL` strings. Specifying this option causes Bowtie 2 to print an asterisk
1891 in those fields instead.
1892
1893 </td></tr>
1894 <tr><td id="bowtie2-options-soft-clipped-unmapped-tlen">
1895
1896 --soft-clipped-unmapped-tlen
1897
1898 </td><td>
1899
1900 Consider soft-clipped bases unmapped when calculating `TLEN`. Only available
1901 in [`--local`] mode.
1902
1903 </td></tr>
1904 <tr><td id="bowtie2-options-sam-no-qname-trunc">
1905
1906 --sam-no-qname-trunc
1907
1908 </td><td>
1909
1910 Suppress standard behavior of truncating readname at first whitespace
1911 at the expense of generating non-standard SAM
1912
1913 </td></tr>
1914 <tr><td id="bowtie2-options-xeq">
1915
1916 --xeq
1917
1918 </td><td>
1919
1920 Use `'='/'X'`, instead of `'M'`, to specify matches/mismatches in SAM record
1921
1922 </td></tr>
1923 <tr><td id="bowtie2-options-sam-append-comment">
1924
1925 --sam-append-comment
1926
1927 </td><td>
1928
1929 Append FASTA/FASTQ comment to SAM record, where a comment is everything
1930 after the first space in the read name.
1931
1932 </td></tr>
1933 <tr><td id="bowtie2-options-sam-opt-config">
1934
1935 --sam-opt-config <config>
1936
1937 </td><td>
1938
1939 Use `<config>` to toggle SAM Optional Fields where `<config>` is a
1940 string of comma delimited, case-insensitive, two-letter tags. Tags
1941 prefixed with a "-" will be turned off and hence will not be included
1942 in the SAM output. The example below turns off the "MD" tag and
1943 enables the `bowtie2`-specific "YP" tag. The config is additive, so,
1944 any default OPT flags that need to be turned off will have to
1945 explicitly specified.
1946
1947 `bowtie2 ... --sam-opt-config "-md,yp"
1948
1949 </td></tr>
1950 </table>
1951
1952 #### Performance options
1953
1954 <table><tr>
1955
1956 <td id="bowtie2-options-o">
1957
1958 -o/--offrate <int>
1959
1960 </td><td>
1961
1962 Override the offrate of the index with `<int>`. If `<int>` is greater
1963 than the offrate used to build the index, then some row markings are
1964 discarded when the index is read into memory. This reduces the memory
1965 footprint of the aligner but requires more time to calculate text
1966 offsets. `<int>` must be greater than the value used to build the
1967 index.
1968
1969 </td></tr>
1970 <tr><td id="bowtie2-options-p">
1971
1972 -p/--threads NTHREADS
1973
1974 </td><td>
1975
1976 Launch `NTHREADS` parallel search threads (default: 1). Threads will run on
1977 separate processors/cores and synchronize when parsing reads and outputting
1978 alignments. Searching for alignments is highly parallel, and speedup is close
1979 to linear. Increasing `-p` increases Bowtie 2's memory footprint. E.g. when
1980 aligning to a human genome index, increasing `-p` from 1 to 8 increases the
1981 memory footprint by a few hundred megabytes. This option is only available if
1982 `bowtie` is linked with the `pthreads` library (i.e. if `BOWTIE_PTHREADS=0` is
1983 not specified at build time).
1984
1985 </td></tr>
1986 <tr><td id="bowtie2-options-reorder">
1987
1988 --reorder
1989
1990 </td><td>
1991
1992 Guarantees that output SAM records are printed in an order corresponding to the
1993 order of the reads in the original input file, even when [`-p`] is set greater
1994 than 1. Specifying `--reorder` and setting [`-p`] greater than 1 causes Bowtie
1995 2 to run somewhat slower and use somewhat more memory than if `--reorder` were
1996 not specified. Has no effect if [`-p`] is set to 1, since output order will
1997 naturally correspond to input order in that case.
1998
1999 </td></tr>
2000 <tr><td id="bowtie2-options-mm">
2001
2002 --mm
2003
2004 </td><td>
2005
2006 Use memory-mapped I/O to load the index, rather than typical file I/O.
2007 Memory-mapping allows many concurrent `bowtie` processes on the same computer to
2008 share the same memory image of the index (i.e. you pay the memory overhead just
2009 once). This facilitates memory-efficient parallelization of `bowtie` in
2010 situations where using [`-p`] is not possible or not preferable.
2011
2012 </td></tr></table>
2013
2014 #### Other options
2015
2016 <table>
2017 <tr><td id="bowtie2-options-qc-filter">
2018
2019 --qc-filter
2020
2021 </td><td>
2022
2023 Filter out reads for which the QSEQ filter field is non-zero. Only has an
2024 effect when read format is [`--qseq`]. Default: off.
2025
2026 </td></tr>
2027 <tr><td id="bowtie2-options-seed">
2028
2029 --seed <int>
2030
2031 </td><td>
2032
2033 Use `<int>` as the seed for pseudo-random number generator. Default: 0.
2034
2035 </td></tr>
2036 <tr><td id="bowtie2-options-non-deterministic">
2037
2038 --non-deterministic
2039
2040 </td><td>
2041
2042 Normally, Bowtie 2 re-initializes its pseudo-random generator for each read. It
2043 seeds the generator with a number derived from (a) the read name, (b) the
2044 nucleotide sequence, (c) the quality sequence, (d) the value of the [`--seed`]
2045 option. This means that if two reads are identical (same name, same
2046 nucleotides, same qualities) Bowtie 2 will find and report the same alignment(s)
2047 for both, even if there was ambiguity. When `--non-deterministic` is specified,
2048 Bowtie 2 re-initializes its pseudo-random generator for each read using the
2049 current time. This means that Bowtie 2 will not necessarily report the same
2050 alignment for two identical reads. This is counter-intuitive for some users,
2051 but might be more appropriate in situations where the input consists of many
2052 identical reads.
2053
2054 </td></tr>
2055 <tr><td id="bowtie2-options-version">
2056
2057 --version
2058
2059 </td><td>
2060
2061 Print version information and quit.
2062
2063 </td></tr>
2064 <tr><td id="bowtie2-options-h">
2065
2066 -h/--help
2067
2068 </td><td>
2069
2070 Print usage information and quit.
2071
2072 </td></tr></table>
2073
2074 SAM output
2075 ----------
2076
2077 Following is a brief description of the [SAM] format as output by `bowtie2`.
2078 For more details, see the [SAM format specification][SAM].
2079
2080 By default, `bowtie2` prints a SAM header with `@HD`, `@SQ` and `@PG` lines.
2081 When one or more [`--rg`] arguments are specified, `bowtie2` will also print
2082 an `@RG` line that includes all user-specified [`--rg`] tokens separated by
2083 tabs.
2084
2085 Each subsequent line describes an alignment or, if the read failed to align, a
2086 read. Each line is a collection of at least 12 fields separated by tabs; from
2087 left to right, the fields are:
2088
2089 1. Name of read that aligned.
2090
2091 Note that the [SAM specification] disallows whitespace in the read name.
2092 If the read name contains any whitespace characters, Bowtie 2 will truncate
2093 the name at the first whitespace character. This is similar to the
2094 behavior of other tools. The standard behavior of truncating at the first
2095 whitespace can be suppressed with `--sam-no-qname-trunc` at the expense of
2096 generating non-standard SAM.
2097
2098 2. Sum of all applicable flags. Flags relevant to Bowtie are:
2099
2100 <table><tr><td>
2101
2102 1
2103
2104 </td><td>
2105
2106 The read is one of a pair
2107
2108 </td></tr><tr><td>
2109
2110 2
2111
2112 </td><td>
2113
2114 The alignment is one end of a proper paired-end alignment
2115
2116 </td></tr><tr><td>
2117
2118 4
2119
2120 </td><td>
2121
2122 The read has no reported alignments
2123
2124 </td></tr><tr><td>
2125
2126 8
2127
2128 </td><td>
2129
2130 The read is one of a pair and has no reported alignments
2131
2132 </td></tr><tr><td>
2133
2134 16
2135
2136 </td><td>
2137
2138 The alignment is to the reverse reference strand
2139
2140 </td></tr><tr><td>
2141
2142 32
2143
2144 </td><td>
2145
2146 The other mate in the paired-end alignment is aligned to the
2147 reverse reference strand
2148
2149 </td></tr><tr><td>
2150
2151 64
2152
2153 </td><td>
2154
2155 The read is mate 1 in a pair
2156
2157 </td></tr><tr><td>
2158
2159 128
2160
2161 </td><td>
2162
2163 The read is mate 2 in a pair
2164
2165 </td></tr></table>
2166
2167 Thus, an unpaired read that aligns to the reverse reference strand
2168 will have flag 16. A paired-end read that aligns and is the first
2169 mate in the pair will have flag 83 (= 64 + 16 + 2 + 1).
2170
2171 3. Name of reference sequence where alignment occurs
2172
2173 4. 1-based offset into the forward reference strand where leftmost
2174 character of the alignment occurs
2175
2176 5. Mapping quality
2177
2178 6. CIGAR string representation of alignment
2179
2180 7. Name of reference sequence where mate's alignment occurs. Set to `=` if the
2181 mate's reference sequence is the same as this alignment's, or `*` if there is no
2182 mate.
2183
2184 8. 1-based offset into the forward reference strand where leftmost character of
2185 the mate's alignment occurs. Offset is 0 if there is no mate.
2186
2187 9. Inferred fragment length. Size is negative if the mate's alignment occurs
2188 upstream of this alignment. Size is 0 if the mates did not align concordantly.
2189 However, size is non-0 if the mates aligned discordantly to the same
2190 chromosome.
2191
2192 10. Read sequence (reverse-complemented if aligned to the reverse strand)
2193
2194 11. ASCII-encoded read qualities (reverse-complemented if the read aligned to
2195 the reverse strand). The encoded quality values are on the [Phred quality]
2196 scale and the encoding is ASCII-offset by 33 (ASCII char `!`), similarly to a
2197 [FASTQ] file.
2198
2199 12. Optional fields. Fields are tab-separated. `bowtie2` outputs zero or more
2200 of these optional fields for each alignment, depending on the type of the
2201 alignment:
2202
2203 <table><tr><td id="bowtie2-build-opt-fields-as">
2204
2205 AS:i:<N>
2206
2207 </td><td>
2208
2209 Alignment score. Can be negative. Can be greater than 0 in [`--local`]
2210 mode (but not in [`--end-to-end`] mode). Only present if SAM record is for
2211 an aligned read.
2212
2213 </td></tr><tr><td id="bowtie2-build-opt-fields-xs">
2214
2215 XS:i:<N>
2216
2217 </td><td>
2218
2219 Alignment score for the best-scoring alignment found other than the
2220 alignment reported. Can be negative. Can be greater than 0 in [`--local`]
2221 mode (but not in [`--end-to-end`] mode). Only present if the SAM record is
2222 for an aligned read and more than one alignment was found for the read.
2223 Note that, when the read is part of a concordantly-aligned pair, this score
2224 could be greater than [`AS:i`].
2225
2226 </td></tr><tr><td id="bowtie2-build-opt-fields-ys">
2227
2228 YS:i:<N>
2229
2230 </td><td>
2231
2232 Alignment score for opposite mate in the paired-end alignment. Only present
2233 if the SAM record is for a read that aligned as part of a paired-end
2234 alignment.
2235
2236 </td></tr><tr><td id="bowtie2-build-opt-fields-xn">
2237
2238 XN:i:<N>
2239
2240 </td><td>
2241
2242 The number of ambiguous bases in the reference covering this alignment.
2243 Only present if SAM record is for an aligned read.
2244
2245 </td></tr><tr><td id="bowtie2-build-opt-fields-xm">
2246
2247 XM:i:<N>
2248
2249 </td><td>
2250
2251 The number of mismatches in the alignment. Only present if SAM record is
2252 for an aligned read.
2253
2254 </td></tr><tr><td id="bowtie2-build-opt-fields-xo">
2255
2256 XO:i:<N>
2257
2258 </td><td>
2259
2260 The number of gap opens, for both read and reference gaps, in the alignment.
2261 Only present if SAM record is for an aligned read.
2262
2263 </td></tr><tr><td id="bowtie2-build-opt-fields-xg">
2264
2265 XG:i:<N>
2266
2267 </td><td>
2268
2269 The number of gap extensions, for both read and reference gaps, in the
2270 alignment. Only present if SAM record is for an aligned read.
2271
2272 </td></tr><tr><td id="bowtie2-build-opt-fields-nm">
2273
2274 NM:i:<N>
2275
2276 </td><td>
2277
2278 The edit distance; that is, the minimal number of one-nucleotide edits
2279 (substitutions, insertions and deletions) needed to transform the read
2280 string into the reference string. Only present if SAM record is for an
2281 aligned read.
2282
2283 </td></tr><tr><td id="bowtie2-build-opt-fields-yf">
2284
2285 YF:Z:<S>
2286
2287 </td><td>
2288
2289 String indicating reason why the read was filtered out. See also:
2290 [Filtering]. Only appears for reads that were filtered out.
2291
2292 </td></tr><tr><td id="bowtie2-build-opt-fields-yt">
2293
2294 YT:Z:<S>
2295
2296 </td><td>
2297
2298 Value of `UU` indicates the read was not part of a pair. Value of `CP`
2299 indicates the read was part of a pair and the pair aligned concordantly.
2300 Value of `DP` indicates the read was part of a pair and the pair aligned
2301 discordantly. Value of `UP` indicates the read was part of a pair but the
2302 pair failed to aligned either concordantly or discordantly.
2303
2304 </td></tr><tr><td id="bowtie2-build-opt-fields-md">
2305
2306 MD:Z:<S>
2307
2308 </td><td>
2309
2310 A string representation of the mismatched reference bases in the alignment.
2311 See [SAM Tags format specification][SAMTags] for details. Only present if SAM record is
2312 for an aligned read.
2313
2314 </td></tr>
2315 </table>
2316
2317
2318 The `bowtie2-build` indexer
2319 ===========================
2320
2321 `bowtie2-build` builds a Bowtie index from a set of DNA sequences.
2322 `bowtie2-build` outputs a set of 6 files with suffixes `.1.bt2`, `.2.bt2`,
2323 `.3.bt2`, `.4.bt2`, `.rev.1.bt2`, and `.rev.2.bt2`. In the case of a large
2324 index these suffixes will have a `bt2l` termination. These files together
2325 constitute the index: they are all that is needed to align reads to that
2326 reference. The original sequence [`FASTA`] files are no longer used by Bowtie 2
2327 once the index is built.
2328
2329 Bowtie 2's `.bt2` index format is different from Bowtie 1's `.ebwt` format, and
2330 they are not compatible with each other.
2331
2332 Use of Karkkainen's [blockwise algorithm] allows `bowtie2-build` to trade off
2333 between running time and memory usage. `bowtie2-build` has three options
2334 governing how it makes this trade: [`-p`/`--packed`], [`--bmax`]/[`--bmaxdivn`],
2335 and [`--dcv`]. By default, `bowtie2-build` will automatically search for the
2336 settings that yield the best running time without exhausting memory. This
2337 behavior can be disabled using the [`-a`/`--noauto`] option.
2338
2339 The indexer provides options pertaining to the "shape" of the index, e.g.
2340 [`--offrate`](#bowtie2-build-options-o) governs the fraction of [Burrows-Wheeler]
2341 rows that are "marked" (i.e., the density of the suffix-array sample; see the
2342 original [FM Index][FM Index Paper] paper for details). All of these options are potentially
2343 profitable trade-offs depending on the application. They have been set to
2344 defaults that are reasonable for most cases according to our experiments. See
2345 [Performance tuning] for details.
2346
2347 `bowtie2-build` can generate either [small or large indexes](#small-and-large-indexes). The wrapper
2348 will decide which based on the length of the input genome. If the reference
2349 does not exceed 4 billion characters but a large index is preferred, the user
2350 can specify [`--large-index`] to force `bowtie2-build` to build a large index
2351 instead.
2352
2353 The Bowtie 2 index is based on the [FM Index][FM Index Paper] of Ferragina and Manzini, which in
2354 turn is based on the [Burrows-Wheeler] transform. The algorithm used to build
2355 the index is based on the [blockwise algorithm] of Karkkainen.
2356
2357
2358 Command Line
2359 ------------
2360
2361 Usage:
2362
2363 bowtie2-build [options]* <reference_in> <bt2_base>
2364
2365 ### Main arguments
2366
2367 <table><tr><td>
2368
2369 <reference_in>
2370
2371 </td><td>
2372
2373 A comma-separated list of [`FASTA`] files containing the reference sequences to be
2374 aligned to, or, if [`-c`](#bowtie2-build-options-c) is specified, the sequences
2375 themselves. E.g., `<reference_in>` might be `chr1.fa,chr2.fa,chrX.fa,chrY.fa`,
2376 or, if [`-c`](#bowtie2-build-options-c) is specified, this might be
2377 `GGTCATCCT,ACGGGTCGT,CCGTTCTATGCGGCTTA`.
2378
2379 </td></tr><tr><td>
2380
2381 <bt2_base>
2382
2383 </td><td>
2384
2385 The basename of the index files to write. By default, `bowtie2-build` writes
2386 files named `NAME.1.bt2`, `NAME.2.bt2`, `NAME.3.bt2`, `NAME.4.bt2`,
2387 `NAME.rev.1.bt2`, and `NAME.rev.2.bt2`, where `NAME` is `<bt2_base>`.
2388
2389 </td></tr></table>
2390
2391 ### Options
2392
2393 <table><tr><td>
2394
2395 -f
2396
2397 </td><td>
2398
2399 The reference input files (specified as `<reference_in>`) are [`FASTA`] files
2400 (usually having extension `.fa`, `.mfa`, `.fna` or similar).
2401
2402 </td></tr><tr><td id="bowtie2-build-options-c">
2403
2404 -c
2405
2406 </td><td>
2407
2408 The reference sequences are given on the command line. I.e. `<reference_in>` is
2409 a comma-separated list of sequences rather than a list of [`FASTA`] files.
2410
2411 </td></tr><tr><td id="bowtie2-build-options-large-index">
2412
2413 --large-index
2414
2415 </td><td>
2416
2417 Force `bowtie2-build` to build a [large index](#small-and-large-indexes), even if the reference is less
2418 than ~ 4 billion nucleotides inlong.
2419
2420 </td></tr>
2421 <tr><td id="bowtie2-build-options-a">
2422
2423 -a/--noauto
2424
2425 </td><td>
2426
2427 Disable the default behavior whereby `bowtie2-build` automatically selects
2428 values for the [`--bmax`], [`--dcv`] and [`--packed`] parameters according to
2429 available memory. Instead, user may specify values for those parameters. If
2430 memory is exhausted during indexing, an error message will be printed; it is up
2431 to the user to try new parameters.
2432
2433 </td></tr><tr><td id="bowtie2-build-options-p">
2434
2435 -p/--packed
2436
2437 </td><td>
2438
2439 Use a packed (2-bits-per-nucleotide) representation for DNA strings. This saves
2440 memory but makes indexing 2-3 times slower. Default: off. This is configured
2441 automatically by default; use [`-a`/`--noauto`] to configure manually.
2442
2443 </td></tr><tr><td id="bowtie2-build-options-bmax">
2444
2445 --bmax <int>
2446
2447 </td><td>
2448
2449 The maximum number of suffixes allowed in a block. Allowing more suffixes per
2450 block makes indexing faster, but increases peak memory usage. Setting this
2451 option overrides any previous setting for [`--bmax`], or [`--bmaxdivn`].
2452 Default (in terms of the [`--bmaxdivn`] parameter) is [`--bmaxdivn`] 4 * number of threads. This is
2453 configured automatically by default; use [`-a`/`--noauto`] to configure manually.
2454
2455 </td></tr><tr><td id="bowtie2-build-options-bmaxdivn">
2456
2457 --bmaxdivn <int>
2458
2459 </td><td>
2460
2461 The maximum number of suffixes allowed in a block, expressed as a fraction of
2462 the length of the reference. Setting this option overrides any previous setting
2463 for [`--bmax`], or [`--bmaxdivn`]. Default: [`--bmaxdivn`] 4 * number of threads. This is
2464 configured automatically by default; use [`-a`/`--noauto`] to configure manually.
2465
2466 </td></tr><tr><td id="bowtie2-build-options-dcv">
2467
2468 --dcv <int>
2469
2470 </td><td>
2471
2472 Use `<int>` as the period for the difference-cover sample. A larger period
2473 yields less memory overhead, but may make suffix sorting slower, especially if
2474 repeats are present. Must be a power of 2 no greater than 4096. Default: 1024.
2475 This is configured automatically by default; use [`-a`/`--noauto`] to configure
2476 manually.
2477
2478 </td></tr><tr><td id="bowtie2-build-options-nodc">
2479
2480 --nodc
2481
2482 </td><td>
2483
2484 Disable use of the difference-cover sample. Suffix sorting becomes
2485 quadratic-time in the worst case (where the worst case is an extremely
2486 repetitive reference). Default: off.
2487
2488 </td></tr><tr><td>
2489
2490 -r/--noref
2491
2492 </td><td>
2493
2494 Do not build the `NAME.3.bt2` and `NAME.4.bt2` portions of the index, which
2495 contain a bitpacked version of the reference sequences and are used for
2496 paired-end alignment.
2497
2498 </td></tr><tr><td>
2499
2500 -3/--justref
2501
2502 </td><td>
2503
2504 Build only the `NAME.3.bt2` and `NAME.4.bt2` portions of the index, which
2505 contain a bitpacked version of the reference sequences and are used for
2506 paired-end alignment.
2507
2508 </td></tr><tr><td id="bowtie2-build-options-o">
2509
2510 -o/--offrate <int>
2511
2512 </td><td>
2513
2514 To map alignments back to positions on the reference sequences, it's necessary
2515 to annotate ("mark") some or all of the [Burrows-Wheeler] rows with their
2516 corresponding location on the genome.
2517 [`-o`/`--offrate`](#bowtie2-build-options-o) governs how many rows get marked:
2518 the indexer will mark every 2^`<int>` rows. Marking more rows makes
2519 reference-position lookups faster, but requires more memory to hold the
2520 annotations at runtime. The default is 5 (every 32nd row is marked; for human
2521 genome, annotations occupy about 340 megabytes).
2522
2523 </td></tr><tr><td>
2524
2525 -t/--ftabchars <int>
2526
2527 </td><td>
2528
2529 The ftab is the lookup table used to calculate an initial [Burrows-Wheeler]
2530 range with respect to the first `<int>` characters of the query. A larger
2531 `<int>` yields a larger lookup table but faster query times. The ftab has size
2532 4^(`<int>`+1) bytes. The default setting is 10 (ftab is 4MB).
2533
2534 </td></tr><tr><td>
2535
2536 --seed <int>
2537
2538 </td><td>
2539
2540 Use `<int>` as the seed for pseudo-random number generator.
2541
2542 </td></tr><tr><td>
2543
2544 --cutoff <int>
2545
2546 </td><td>
2547
2548 Index only the first `<int>` bases of the reference sequences (cumulative across
2549 sequences) and ignore the rest.
2550
2551 </td></tr><tr><td>
2552
2553 -q/--quiet
2554
2555 </td><td>
2556
2557 `bowtie2-build` is verbose by default. With this option `bowtie2-build` will
2558 print only error messages.
2559
2560 </td></tr><tr><td>
2561
2562 --threads <int>
2563
2564 </td><td>
2565
2566 By default `bowtie2-build` is using only one thread. Increasing the number
2567 of threads will speed up the index building considerably in most cases.
2568
2569 </td></tr><tr><td>
2570
2571 -h/--help
2572
2573 </td><td>
2574
2575 Print usage information and quit.
2576
2577 </td></tr><tr><td>
2578
2579 --version
2580
2581 </td><td>
2582
2583 Print version information and quit.
2584
2585 </td></tr></table>
2586
2587 The `bowtie2-inspect` index inspector
2588 =====================================
2589
2590 `bowtie2-inspect` extracts information from a Bowtie index about what kind of
2591 index it is and what reference sequences were used to build it. When run without
2592 any options, the tool will output a [`FASTA`] file containing the sequences of the
2593 original references (with all non-`A`/`C`/`G`/`T` characters converted to `N`s).
2594 It can also be used to extract just the reference sequence names using the
2595 [`-n`/`--names`] option or a more verbose summary using the [`-s`/`--summary`]
2596 option.
2597
2598 Command Line
2599 ------------
2600
2601 Usage:
2602
2603 bowtie2-inspect [options]* <bt2_base>
2604
2605 ### Main arguments
2606
2607 <table><tr><td>
2608
2609 <bt2_base>
2610
2611 </td><td>
2612
2613 The basename of the index to be inspected. The basename is name of any of the
2614 index files but with the `.X.bt2` or `.rev.X.bt2` suffix omitted.
2615 `bowtie2-inspect` first looks in the current directory for the index files, then
2616 in the directory specified in the `BOWTIE2_INDEXES` environment variable.
2617
2618 </td></tr></table>
2619
2620 ### Options
2621
2622 <table><tr><td>
2623
2624 -a/--across <int>
2625
2626 </td><td>
2627
2628 When printing [`FASTA`] output, output a newline character every `<int>` bases
2629 (default: 60).
2630
2631 </td></tr><tr><td id="bowtie2-inspect-options-n">
2632
2633 -n/--names
2634
2635 </td><td>
2636
2637 Print reference sequence names, one per line, and quit.
2638
2639 </td></tr><tr><td id="bowtie2-inspect-options-s">
2640
2641 -s/--summary
2642
2643 </td><td>
2644
2645 Print a summary that includes information about index settings, as well as the
2646 names and lengths of the input sequences. The summary has this format:
2647
2648 Colorspace <0 or 1>
2649 SA-Sample 1 in <sample>
2650 FTab-Chars <chars>
2651 Sequence-1 <name> <len>
2652 Sequence-2 <name> <len>
2653 ...
2654 Sequence-N <name> <len>
2655
2656 Fields are separated by tabs. Colorspace is always set to 0 for Bowtie 2.
2657
2658 </td></tr><tr><td id="bowtie2-inspect-options-o">
2659
2660 -o/--output <filename>
2661
2662 </td><td>
2663
2664 Save output to user-specified filename (default: stdout)
2665
2666 </td></tr><tr><td>
2667
2668 -v/--verbose
2669
2670 </td><td>
2671
2672 Print verbose output (for debugging).
2673
2674 </td></tr><tr><td>
2675
2676 --version
2677
2678 </td><td>
2679
2680 Print version information and quit.
2681
2682 </td></tr><tr><td>
2683
2684 -h/--help
2685
2686 </td><td>
2687
2688 Print usage information and quit.
2689
2690 </td></tr></table>
2691
2692 Getting started with Bowtie 2: Lambda phage example
2693 ===================================================
2694
2695 Bowtie 2 comes with some example files to get you started. The example files
2696 are not scientifically significant; we use the [Lambda phage] reference genome
2697 simply because it's short, and the reads were generated by a computer program,
2698 not a sequencer. However, these files will let you start running Bowtie 2 and
2699 downstream tools right away.
2700
2701 First follow the manual instructions to [obtain Bowtie 2]. Set the `BT2_HOME`
2702 environment variable to point to the new Bowtie 2 directory containing the
2703 `bowtie2`, `bowtie2-build` and `bowtie2-inspect` binaries. This is important,
2704 as the `BT2_HOME` variable is used in the commands below to refer to that
2705 directory.
2706
2707
2708 Indexing a reference genome
2709 ---------------------------
2710
2711 To create an index for the [Lambda phage] reference genome included with Bowtie
2712 2, create a new temporary directory (it doesn't matter where), change into that
2713 directory, and run:
2714
2715 $BT2_HOME/bowtie2-build $BT2_HOME/example/reference/lambda_virus.fa lambda_virus
2716
2717 The command should print many lines of output then quit. When the command
2718 completes, the current directory will contain four new files that all start with
2719 `lambda_virus` and end with `.1.bt2`, `.2.bt2`, `.3.bt2`, `.4.bt2`,
2720 `.rev.1.bt2`, and `.rev.2.bt2`. These files constitute the index - you're done!
2721
2722 You can use `bowtie2-build` to create an index for a set of [`FASTA`] files obtained
2723 from any source, including sites such as [UCSC], [NCBI], and [Ensembl]. When
2724 indexing multiple [`FASTA`] files, specify all the files using commas to separate
2725 file names. For more details on how to create an index with `bowtie2-build`,
2726 see the [manual section on index building]. You may also want to bypass this
2727 process by obtaining a pre-built index. See [using a pre-built index] below
2728 for an example.
2729
2730
2731 Aligning example reads
2732 ----------------------
2733
2734 Stay in the directory created in the previous step, which now contains the
2735 `lambda_virus` index files. Next, run:
2736
2737 $BT2_HOME/bowtie2 -x lambda_virus -U $BT2_HOME/example/reads/reads_1.fq -S eg1.sam
2738
2739 This runs the Bowtie 2 aligner, which aligns a set of unpaired reads to the
2740 [Lambda phage] reference genome using the index generated in the previous step.
2741 The alignment results in SAM format are written to the file `eg1.sam`, and a
2742 short alignment summary is written to the console. (Actually, the summary is
2743 written to the "standard error" or "stderr" filehandle, which is typically
2744 printed to the console.)
2745
2746 To see the first few lines of the SAM output, run:
2747
2748 head eg1.sam
2749
2750 You will see something like this:
2751
2752 @HD VN:1.0 SO:unsorted
2753 @SQ SN:gi|9626243|ref|NC_001416.1| LN:48502
2754 @PG ID:bowtie2 PN:bowtie2 VN:2.0.1
2755 r1 0 gi|9626243|ref|NC_001416.1| 18401 42 122M * 0 0 TGAATGCGAACTCCGGGACGCTCAGTAATGTGACGATAGCTGAAAACTGTACGATAAACNGTACGCTGAGGGCAGAAAAAATCGTCGGGGACATTNTAAAGGCGGCGAGCGCGGCTTTTCCG +"@6<:27(F&5)9"B):%B+A-%5A?2$HCB0B+0=D<7E/<.03#!.F77@6B==?C"7>;))%;,3-$.A06+<-1/@@?,26">=?*@'0;$:;??G+:#+(A?9+10!8!?()?7C> AS:i:-5 XN:i:0 XM:i:3 XO:i:0 XG:i:0 NM:i:3 MD:Z:59G13G21G26 YT:Z:UU
2756 r2 0 gi|9626243|ref|NC_001416.1| 8886 42 275M * 0 0 NTTNTGATGCGGGCTTGTGGAGTTCAGCCGATCTGACTTATGTCATTACCTATGAAATGTGAGGACGCTATGCCTGTACCAAATCCTACAATGCCGGTGAAAGGTGCCGGGATCACCCTGTGGGTTTATAAGGGGATCGGTGACCCCTACGCGAATCCGCTTTCAGACGTTGACTGGTCGCGTCTGGCAAAAGTTAAAGACCTGACGCCCGGCGAACTGACCGCTGAGNCCTATGACGACAGCTATCTCGATGATGAAGATGCAGACTGGACTGC (#!!'+!$""%+(+)'%)%!+!(&++)''"#"#&#"!'!("%'""("+&%$%*%%#$%#%#!)*'(#")(($&$'&%+&#%*)*#*%*')(%+!%%*"$%"#+)$&&+)&)*+!"*)!*!("&&"*#+"&"'(%)*("'!$*!!%$&&&$!!&&"(*"$&"#&!$%'%"#)$#+%*+)!&*)+(""#!)!%*#"*)*')&")($+*%%)!*)!('(%""+%"$##"#+(('!*(($*'!"*('"+)&%#&$+('**$$&+*&!#%)')'(+(!%+ AS:i:-14 XN:i:0 XM:i:8 XO:i:0 XG:i:0 NM:i:8 MD:Z:0A0C0G0A108C23G9T81T46 YT:Z:UU
2757 r3 16 gi|9626243|ref|NC_001416.1| 11599 42 338M * 0 0 GGGCGCGTTACTGGGATGATCGTGAAAAGGCCCGTCTTGCGCTTGAAGCCGCCCGAAAGAAGGCTGAGCAGCAGACTCAAGAGGAGAAAAATGCGCAGCAGCGGAGCGATACCGAAGCGTCACGGCTGAAATATACCGAAGAGGCGCAGAAGGCTNACGAACGGCTGCAGACGCCGCTGCAGAAATATACCGCCCGTCAGGAAGAACTGANCAAGGCACNGAAAGACGGGAAAATCCTGCAGGCGGATTACAACACGCTGATGGCGGCGGCGAAAAAGGATTATGAAGCGACGCTGTAAAAGCCGAAACAGTCCAGCGTGAAGGTGTCTGCGGGCGAT 7F$%6=$:9B@/F'>=?!D?@0(:A*)7/>9C>6#1<6:C(.CC;#.;>;2'$4D:?&B!>689?(0(G7+0=@37F)GG=>?958.D2E04C<E,*AD%G0.%$+A:'H;?8<72:88?E6((CF)6DF#.)=>B>D-="C'B080E'5BH"77':"@70#4%A5=6.2/1>;9"&-H6)=$/0;5E:<8G!@::1?2DC7C*;@*#.1C0.D>H/20,!"C-#,6@%<+<D(AG-).?&#0.00'@)/F8?B!&"170,)>:?<A7#1(A@0E#&A.*DC.E")AH"+.,5,2>5"2?:G,F"D0B8D-6$65D<D!A/38860.*4;4B<*31?6 AS:i:-22 XN:i:0 XM:i:8 XO:i:0 XG:i:0 NM:i:8 MD:Z:80C4C16A52T23G30A8T76A41 YT:Z:UU
2758 r4 0 gi|9626243|ref|NC_001416.1| 40075 42 184M * 0 0 GGGCCAATGCGCTTACTGATGCGGAATTACGCCGTAAGGCCGCAGATGAGCTTGTCCATATGACTGCGAGAATTAACNGTGGTGAGGCGATCCCTGAACCAGTAAAACAACTTCCTGTCATGGGCGGTAGACCTCTAAATCGTGCACAGGCTCTGGCGAAGATCGCAGAAATCAAAGCTAAGT(=8B)GD04*G%&4F,1'A>.C&7=F$,+#6!))43C,5/5+)?-/0>/D3=-,2/+.1?@->;)00!'3!7BH$G)HG+ADC'#-9F)7<7"$?&.>0)@5;4,!0-#C!15CF8&HB+B==H>7,/)C5)5*+(F5A%D,EA<(>G9E0>7&/E?4%;#'92)<5+@7:A.(BG@[email protected] AS:i:-1 XN:i:0 XM:i:1 XO:i:0 XG:i:0 NM:i:1 MD:Z:77C106 YT:Z:UU
2759 r5 0 gi|9626243|ref|NC_001416.1| 48010 42 138M * 0 0 GTCAGGAAAGTGGTAAAACTGCAACTCAATTACTGCAATGCCCTCGTAATTAAGTGAATTTACAATATCGTCCTGTTCGGAGGGAAGAACGCGGGATGTTCATTCTTCATCACTTTTAATTGATGTATATGCTCTCTT 9''%<D)A03E1-*7=),:F/0!6,D9:H,<9D%:0B(%'E,(8EFG$E89B$27G8F*2+4,-!,0D5()&=(FGG:5;3*@/.0F-G#5#3->('FDFEG?)5.!)"AGADB3?6(@H(:B<>6!>;>6>G,."?% AS:i:0 XN:i:0 XM:i:0 XO:i:0 XG:i:0 NM:i:0 MD:Z:138 YT:Z:UU
2760 r6 16 gi|9626243|ref|NC_001416.1| 41607 42 72M2D119M * 0 0 TCGATTTGCAAATACCGGAACATCTCGGTAACTGCATATTCTGCATTAAAAAATCAACGCAAAAAATCGGACGCCTGCAAAGATGAGGAGGGATTGCAGCGTGTTTTTAATGAGGTCATCACGGGATNCCATGTGCGTGACGGNCATCGGGAAACGCCAAAGGAGATTATGTACCGAGGAAGAATGTCGCT 1H#G;H"$E*E#&"*)2%66?=9/9'=;4)4/>@%+5#@#$4A*!<D=="8#1*A9BA=:(1+#C&.#(3#H=9E)AC*5,AC#E'536*2?)H14?>9'B=7(3H/B:+A:8%1-+#(E%&$$&14"76D?>7(&20H5%*&CF8!G5B+A4F$7(:"'?0$?G+$)B-?2<0<F=D!38BH,%=8&5@+ AS:i:-13 XN:i:0 XM:i:2 XO:i:1 XG:i:2 NM:i:4 MD:Z:72^TT55C15A47 YT:Z:UU
2761 r7 16 gi|9626243|ref|NC_001416.1| 4692 42 143M * 0 0 TCAGCCGGACGCGGGCGCTGCAGCCGTACTCGGGGATGACCGGTTACAACGGCATTATCGCCCGTCTGCAACAGGCTGCCAGCGATCCGATGGTGGACAGCATTCTGCTCGATATGGACANGCCCGGCGGGATGGTGGCGGGG -"/@*7A0)>2,AAH@&"%B)*5*23B/,)90.B@%=FE,E063C9?,:26$-0:,.,1849'4.;F>FA;76+5&$<C":$!A*,<B,<)@<'85D%C*:)30@85;?.B$05=@95DCDH<53!8G:F:B7/A.E':434> AS:i:-6 XN:i:0 XM:i:2 XO:i:0 XG:i:0 NM:i:2 MD:Z:98G21C22 YT:Z:UU
2762
2763 The first few lines (beginning with `@`) are SAM header lines, and the rest of
2764 the lines are SAM alignments, one line per read or mate. See the [Bowtie 2
2765 manual section on SAM output] and the [SAM specification] for details about how
2766 to interpret the SAM file format.
2767
2768
2769 Paired-end example
2770 ------------------
2771
2772 To align paired-end reads included with Bowtie 2, stay in the same directory and
2773 run:
2774
2775 $BT2_HOME/bowtie2 -x lambda_virus -1 $BT2_HOME/example/reads/reads_1.fq -2 $BT2_HOME/example/reads/reads_2.fq -S eg2.sam
2776
2777 This aligns a set of paired-end reads to the reference genome, with results
2778 written to the file `eg2.sam`.
2779
2780 Local alignment example
2781 -----------------------
2782
2783 To use [local alignment] to align some longer reads included with Bowtie 2, stay
2784 in the same directory and run:
2785
2786 $BT2_HOME/bowtie2 --local -x lambda_virus -U $BT2_HOME/example/reads/longreads.fq -S eg3.sam
2787
2788 This aligns the long reads to the reference genome using local alignment, with
2789 results written to the file `eg3.sam`.
2790
2791
2792 Using SAMtools/BCFtools downstream
2793 ----------------------------------
2794
2795 [SAMtools] is a collection of tools for manipulating and analyzing SAM and BAM
2796 alignment files. [BCFtools] is a collection of tools for calling variants and
2797 manipulating VCF and BCF files, and it is typically distributed with [SAMtools].
2798 Using these tools together allows you to get from alignments in SAM format to
2799 variant calls in VCF format. This example assumes that `samtools` and
2800 `bcftools` are installed and that the directories containing these binaries are
2801 in your [PATH environment variable].
2802
2803 Run the paired-end example:
2804
2805 $BT2_HOME/bowtie2 -x $BT2_HOME/example/index/lambda_virus -1 $BT2_HOME/example/reads/reads_1.fq -2 $BT2_HOME/example/reads/reads_2.fq -S eg2.sam
2806
2807 Use `samtools view` to convert the SAM file into a BAM file. BAM is the
2808 binary format corresponding to the SAM text format. Run:
2809
2810 samtools view -bS eg2.sam > eg2.bam
2811
2812 Use `samtools sort` to convert the BAM file to a sorted BAM file.
2813
2814 samtools sort eg2.bam -o eg2.sorted.bam
2815
2816 We now have a sorted BAM file called `eg2.sorted.bam`. Sorted BAM is a useful
2817 format because the alignments are (a) compressed, which is convenient for
2818 long-term storage, and (b) sorted, which is conveneint for variant discovery.
2819 To generate variant calls in VCF format, run:
2820
2821 bcftools mpileup -f $BT2_HOME/example/reference/lambda_virus.fa eg2.sorted.bam | bcftools view -Ov - > eg2.raw.bcf
2822
2823 Then to view the variants, run:
2824
2825 bcftools view eg2.raw.bcf
2826
2827 See the official SAMtools guide to [Calling SNPs/INDELs with SAMtools/BCFtools]
2828 for more details and variations on this process.
2829
2830 [BCFtools]: http://samtools.sourceforge.net/mpileup.shtml
2831 [BLAST]: http://blast.ncbi.nlm.nih.gov/Blast.cgi
2832 [BLAT]: http://genome.ucsc.edu/cgi-bin/hgBlat?command=start
2833 [BWA]: http://bio-bwa.sourceforge.net/
2834 [BWT]: http://en.wikipedia.org/wiki/Burrows-Wheeler_transform
2835 [Blockwise algorithm]: http://portal.acm.org/citation.cfm?id=1314852
2836 [Bowtie 1 does]: http://genomebiology.com/2009/10/3/R25
2837 [Bowtie 1 paper]: http://genomebiology.com/2009/10/3/R25
2838 [Bowtie 1]: http://bowtie-bio.sf.net
2839 [Bowtie 2 manual section on SAM output]: #sam-output
2840 [Bowtie 2]: http://bowtie-bio.sf.net/bowtie2
2841 [Bowtie paper]: http://genomebiology.com/2009/10/3/R25
2842 [Bowtie]: http://bowtie-bio.sf.net
2843 [Burrows-Wheeler Transform]: http://en.wikipedia.org/wiki/Burrows-Wheeler_transform
2844 [Burrows-Wheeler]: http://en.wikipedia.org/wiki/Burrows-Wheeler_transform
2845 [Calling SNPs/INDELs with SAMtools/BCFtools]: http://samtools.sourceforge.net/mpileup.shtml
2846 [Crossbow]: http://bowtie-bio.sf.net/crossbow
2847 [Cufflinks]: http://cufflinks.cbcb.umd.edu/
2848 [Download]: https://sourceforge.net/projects/bowtie-bio/files/bowtie2/
2849 [Ensembl]: http://www.ensembl.org/
2850 [`FASTA`]: https://en.wikipedia.org/wiki/FASTA
2851 [FASTQ]: http://en.wikipedia.org/wiki/FASTQ_format
2852 [FM Index Paper]: http://portal.acm.org/citation.cfm?id=796543
2853 [FM Index Wiki]: http://en.wikipedia.org/wiki/FM-index
2854 [Filtering]: #filtering
2855 [GATK]: http://www.broadinstitute.org/gsa/wiki/index.php/The_Genome_Analysis_Toolkit
2856 [GPLv3 license]: http://www.gnu.org/licenses/gpl-3.0.html
2857 [GnuWin32]: http://gnuwin32.sf.net/packages/coreutils.htm
2858 [IUPAC nucleotide codes]: http://www.bioinformatics.org/sms/iupac.html
2859 [Lambda phage]: http://en.wikipedia.org/wiki/Lambda_phage
2860 [MSYS]: http://www.mingw.org/wiki/msys
2861 [MUMmer]: http://mummer.sourceforge.net/
2862 [Mates can overlap, contain or dovetail each other]: #mates-can-overlap-contain-or-dovetail-each-other
2863 [MinGW]: http://www.mingw.org/
2864 [Myrna]: http://bowtie-bio.sf.net/myrna
2865 [NCBI]: http://www.ncbi.nlm.nih.gov/sites/genome
2866 [NUCmer]: http://mummer.sourceforge.net/manual/#nucmer
2867 [Needleman-Wunsch]: http://en.wikipedia.org/wiki/Needleman-Wunsch_algorithm
2868 [PATH environment variable]: http://en.wikipedia.org/wiki/PATH_(variable)
2869 [PATH]: http://en.wikipedia.org/wiki/PATH_(variable)
2870 [Performance tuning]: #performance-tuning
2871 [Phred quality]: http://en.wikipedia.org/wiki/Phred_quality_score
2872 [SAM format specification]: http://samtools.sf.net/SAM1.pdf
2873 [SAM specification]: http://samtools.sourceforge.net/SAM1.pdf
2874 [SAMTags]: https://samtools.github.io/hts-specs/SAMtags.pdf
2875 [SAM]: http://samtools.sourceforge.net/SAM1.pdf
2876 [SAMtools]: http://samtools.sourceforge.net
2877 [Smith-Waterman]: http://en.wikipedia.org/wiki/Smith_waterman
2878 [TopHat]: http://tophat.cbcb.umd.edu/
2879 [UCSC]: http://genome.ucsc.edu/cgi-bin/hgGateway
2880 [Xcode]: http://developer.apple.com/xcode/
2881 [`+I`/`--minins`]: #bowtie2-options-I
2882 [`+I`]: #bowtie2-options-I
2883 [`+R`]: #bowtie2-options-R
2884 [`+S`/`--sam`]: #bowtie2-options-S
2885 [`+S`]: #bowtie2-options-S
2886 [`+U`]: #bowtie2-options-U
2887 [`+X`/`--maxins`]: #bowtie2-options-X
2888 [`+X`]: #bowtie2-options-X
2889 [`--al-bz2`]: #bowtie2-options-al
2890 [`--al-conc-bz2`]: #bowtie2-options-al-conc
2891 [`--al-conc-gz`]: #bowtie2-options-al-conc
2892 [`--al-conc-lz4`]: #bowtie2-options-al-conc
2893 [`--al-conc`]: #bowtie2-options-al-conc
2894 [`--al-gz`]: #bowtie2-options-al
2895 [`--al-lz4`]: #bowtie2-options-al
2896 [`--al`]: #bowtie2-options-al
2897 [`--align-paired-reads`]: #bowtie2-options-align-paired-reads
2898 [`--bmax`]: #bowtie2-build-options-bmax
2899 [`--bmaxdivn`]: #bowtie2-build-options-bmaxdivn
2900 [`--dcv`]: #bowtie2-build-options-dcv
2901 [`--dovetail`]: #bowtie2-options-dovetail
2902 [`--dpad`]: #bowtie2-options-dpad
2903 [`--end-to-end`]: #bowtie2-options-end-to-end
2904 [`--fast-local`]: #bowtie2-options-fast-local
2905 [`--fast`]: #bowtie2-options-fast
2906 [`--ff`]: #bowtie2-options-fr
2907 [`--fr`/`--rf`/`--ff`]: #bowtie2-options-fr
2908 [`--fr`]: #bowtie2-options-fr
2909 [`--gbar`]: #bowtie2-options-gbar
2910 [`--ignore-quals`]: #bowtie2-options-ignore-quals
2911 [`--int-quals`]: #bowtie2-options-int-quals
2912 [`--interleaved`]: #bowtie2-options-interleaved
2913 [`--sra-acc`]: #bowtie2-options-sra-acc
2914 [`--large-index`]: #bowtie2-build-options-large-index
2915 [`--local`]: #bowtie2-options-local
2916 [`--ma`]: #bowtie2-options-ma
2917 [`--met-file`]: #bowtie2-options-met-file
2918 [`--met-stderr`]: #bowtie2-options-met-stderr
2919 [`--met`]: #bowtie2-options-met
2920 [`--mm`]: #bowtie2-options-mm
2921 [`--mp`]: #bowtie2-options-mp
2922 [`--n-ceil`]: #bowtie2-options-n-ceil
2923 [`--no-1mm-upfront`]: #bowtie2-options-no-1mm-upfront
2924 [`--no-contain`]: #bowtie2-options-no-contain
2925 [`--no-discordant`]: #bowtie2-options-no-discordant
2926 [`--no-hd`]: #bowtie2-options-no-hd
2927 [`--no-mixed`]: #bowtie2-options-no-mixed
2928 [`--no-overlap`]: #bowtie2-options-no-overlap
2929 [`--no-sq`]: #bowtie2-options-no-sq
2930 [`--no-unal`]: #bowtie2-options-no-unal
2931 [`--nodc`]: #bowtie2-build-options-nodc
2932 [`--nofw`]: #bowtie2-options-nofw
2933 [`--non-deterministic`]: #bowtie2-options-non-deterministic
2934 [`--np`]: #bowtie2-options-np
2935 [`--offrate`]: #bowtie2-options-o
2936 [`--omit-sec-seq`]: #bowtie2-options-omit-sec-seq
2937 [`--packed`]: #bowtie2-build-options-p
2938 [`--phred33`]: #bowtie2-options-phred33-quals
2939 [`--phred64`]: #bowtie2-options-phred64-quals
2940 [`--preserve-tags`]: #bowtie2-options-preserve-tags
2941 [`--qc-filter`]: #bowtie2-options-qc-filter
2942 [`--qseq`]: #bowtie2-options-qseq
2943 [`--quiet`]: #bowtie2-options-quiet
2944 [`--rdg`]: #bowtie2-options-rdg
2945 [`--reorder`]: #bowtie2-options-reorder
2946 [`--rf`]: #bowtie2-options-fr
2947 [`--rfg`]: #bowtie2-options-rfg
2948 [`--rg-id`]: #bowtie2-options-rg-id
2949 [`--rg`]: #bowtie2-options-rg
2950 [`--score-min`]: #bowtie2-options-score-min
2951 [`--seed`]: #bowtie2-options-seed
2952 [`--sensitive-local`]: #bowtie2-options-sensitive-local
2953 [`--sensitive`]: #bowtie2-options-sensitive
2954 [`--soft-clipped-unmapped-tlen`]: #bowtie2-options-soft-clipped-unmapped-tlen
2955 [`--solexa-quals`]: #bowtie2-options-solexa-quals
2956 [`--tab5`]: #bowtie2-options-tab5
2957 [`--tab6`]: #bowtie2-options-tab6
2958 [`--un-bz2`]: #bowtie2-options-un
2959 [`--un-conc-bz2`]: #bowtie2-options-un-conc
2960 [`--un-conc-gz`]: #bowtie2-options-un-conc
2961 [`--un-conc-lz4`]: #bowtie2-options-un-conc
2962 [`--un-conc`]: #bowtie2-options-un-conc
2963 [`--un-gz`]: #bowtie2-options-un
2964 [`--un-lz4`]: #bowtie2-options-un
2965 [`--un`]: #bowtie2-options-un
2966 [`--version`]: #bowtie2-options-version
2967 [`--very-fast-local`]: #bowtie2-options-very-fast-local
2968 [`--very-fast`]: #bowtie2-options-very-fast
2969 [`--very-sensitive-local`]: #bowtie2-options-very-sensitive-local
2970 [`--very-sensitive`]: #bowtie2-options-very-sensitive
2971 [`--xeq`]: #bowtie2-options-xeq
2972 [`--sam-append-comment`]: #bowtie2-options-sam-append-comment
2973 [`--sam-opt-config`]: #bowtie2-options-sam-opt-config
2974 [`-1`]: #bowtie2-options-1
2975 [`-2`]: #bowtie2-options-2
2976 [`-3`/`--trim3`]: #bowtie2-options-3
2977 [`-3`]: #bowtie2-options-3
2978 [`-5`/`--trim5`]: #bowtie2-options-5
2979 [`-5`]: #bowtie2-options-5
2980 [`--trim-to`]: #bowtie2-options-trim-to
2981 [`-D`]: #bowtie2-options-D
2982 [`-L`]: #bowtie2-options-L
2983 [`-N`]: #bowtie2-options-N
2984 [`-a`/`--noauto`]: #bowtie2-build-options-a
2985 [`-a`]: #bowtie2-options-a
2986 <!-- fasta-continuous option does not exist but was added to prevent
2987 warnings due to the case insensitive nature of markdown URLs -->
2988 [`-F`/--fasta-continuous]: #bowtie2-options-F
2989 [`-b`]: #bowtie2-options-b
2990 [`-c`]: #bowtie2-options-c
2991 [`-f`]: #bowtie2-options-f
2992 [`-i`]: #bowtie2-options-i
2993 [`-k`]: #bowtie2-options-k
2994 [`-m`]: #bowtie2-options-m
2995 [`-n`/`--names`]: #bowtie2-inspect-options-n
2996 [`-o`/`--offrate`]: #bowtie2-options-o
2997 [`-o`/`--output`]: #bowtie2-inspect-options-o
2998 [`-o`]: #bowtie2-options-o
2999 [`-p`/`--packed`]: #bowtie2-build-options-p
3000 [`-p`/`--threads`]: #bowtie2-options-p
3001 [`-p`]: #bowtie2-options-p
3002 [`-q`]: #bowtie2-options-q
3003 [`-r`]: #bowtie2-options-r
3004 [`-s`/`--skip`]: #bowtie2-options-s
3005 [`-s`/`--summary`]: #bowtie2-inspect-options-s
3006 [`-s`]: #bowtie2-options-s
3007 [`-t`/`--time`]: #bowtie2-options-t
3008 [`-t`]: #bowtie2-options-t
3009 [`-u`/`--qupto`]: #bowtie2-options-u
3010 [`-u`]: #bowtie2-options-u
3011 [`-x`]: #bowtie2-options-x
3012 [`AS:i`]: #bowtie2-build-opt-fields-as
3013 [`MD:Z`]: #bowtie2-build-opt-fields-md
3014 [`NM:i`]: #bowtie2-build-opt-fields-nm
3015 [`XG:i`]: #bowtie2-build-opt-fields-xg
3016 [`XM:i`]: #bowtie2-build-opt-fields-xm
3017 [`XN:i`]: #bowtie2-build-opt-fields-xn
3018 [`XO:i`]: #bowtie2-build-opt-fields-xo
3019 [`XS:i`]: #bowtie2-build-opt-fields-xs
3020 [`YF:Z`]: #bowtie2-build-opt-fields-yf
3021 [`YS:i`]: #bowtie2-build-opt-fields-ys
3022 [`YT:Z`]: #bowtie2-build-opt-fields-yt
3023 [bi-directional BWT approach]: http://www.computer.org/portal/web/csdl/doi/10.1109/BIBM.2009.42
3024 [documentation for the preset options]: #preset-options-in---end-to-end-mode
3025 [end-to-end alignment]: #end-to-end-alignment-versus-local-alignment
3026 [filtered out]: #filtering
3027 [local alignment]: #end-to-end-alignment-versus-local-alignment
3028 [manual section on index building]: #the-bowtie2-build-indexer
3029 [multiseed alignment]: #multiseed-heuristic
3030 [multiseed heuristic]: #multiseed-heuristic
3031 [obtain Bowtie 2]: #obtaining-bowtie-2
3032 [overlap ambiguous characters]: #ambiguous-characters
3033 [paired-end alignment]: #aligning-pairs
3034 [preset options]: #presets-setting-many-settings-at-once
3035 [pthreads]: http://sourceware.org/pthreads-win32/
3036 [reporting]: #reporting
3037 [scoring scheme]: #scores-higher-more-similar
3038 [setting function options]: #setting-function-options
3039 [sourceforge site]: https://sourceforge.net/projects/bowtie-bio/files/bowtie2/
3040 [structural variants]: http://www.ncbi.nlm.nih.gov/dbvar/content/overview/
3041 [using a pre-built index]: #using-a-pre-built-index
3042 [valid alignment]: #valid-alignments-meet-or-exceed-the-minimum-score-threshold
3043 [yields a larger memory footprint]: #fm-index-memory-footprint
3044 [libsais]: https://github.com/IlyaGrebnov/libsais