Debian Codegraph @

MANUAL

raw
1 Introduction
2
3 Bowtie 2 is an ultrafast and memory-efficient tool for aligning
4 sequencing reads to long reference sequences. It is particularly good at
5 aligning reads of about 50 up to 100s of characters to relatively long
6 (e.g. mammalian) genomes. Bowtie 2 indexes the genome with an FM Index
7 (based on the Burrows-Wheeler Transform or BWT) to keep its memory
8 footprint small: for the human genome, its memory footprint is typically
9 around 3.2 gigabytes of RAM. Bowtie 2 supports gapped, local, and
10 paired-end alignment modes. Multiple processors can be used
11 simultaneously to achieve greater alignment speed.
12
13 Bowtie 2 outputs alignments in SAM format, enabling interoperation with
14 a large number of other tools (e.g. SAMtools, GATK) that use SAM. Bowtie
15 2 is distributed under the GPLv3 license, and it runs on the command
16 line under Windows, Mac OS X and Linux and BSD.
17
18 Bowtie 2 is often the first step in pipelines for comparative genomics,
19 including for variation calling, ChIP-seq, RNA-seq, BS-seq. Bowtie 2 and
20 Bowtie (also called "Bowtie 1" here) are also tightly integrated into
21 many other tools, some of which are listed here.
22
23 If you use Bowtie 2 for your published research, please cite our work.
24 Papers describing Bowtie 2 are:
25
26 - Langmead B, Wilks C, Antonescu V, Charles R. Scaling read aligners to
27 hundreds of threads on general-purpose processors. Bioinformatics.
28 2018 Jul 18. doi: 10.1093/bioinformatics/bty648.
29
30 - Langmead B, Salzberg SL. Fast gapped-read alignment with Bowtie 2.
31 Nature Methods. 2012 Mar 4;9(4):357-9. doi: 10.1038/nmeth.1923.
32
33 How is Bowtie 2 different from Bowtie 1?
34
35 Bowtie 1 was released in 2009 and was geared toward aligning the
36 relatively short sequencing reads (up to 25-50 nucleotides) prevalent at
37 the time. Since then, technology has improved both sequencing throughput
38 (more nucleotides produced per sequencer per day) and read length (more
39 nucleotides per read).
40
41 The chief differences between Bowtie 1 and Bowtie 2 are:
42
43 1. For reads longer than about 50 bp Bowtie 2 is generally faster, more
44 sensitive, and uses less memory than Bowtie 1. For relatively short
45 reads (e.g. less than 50 bp) Bowtie 1 is sometimes faster and/or
46 more sensitive.
47
48 2. Bowtie 2 supports gapped alignment with affine gap penalties. Number
49 of gaps and gap lengths are not restricted, except by way of the
50 configurable scoring scheme. Bowtie 1 finds just ungapped
51 alignments.
52
53 3. Bowtie 2 supports local alignment, which doesn't require reads to
54 align end-to-end. Local alignments might be "trimmed" ("soft
55 clipped") at one or both extremes in a way that optimizes alignment
56 score. Bowtie 2 also supports end-to-end alignment which, like
57 Bowtie 1, requires that the read align entirely.
58
59 4. There is no upper limit on read length in Bowtie 2. Bowtie 1 had an
60 upper limit of around 1000 bp.
61
62 5. Bowtie 2 allows alignments to overlap ambiguous characters (e.g. Ns)
63 in the reference. Bowtie 1 does not.
64
65 6. Bowtie 2 does away with Bowtie 1's notion of alignment "stratum",
66 and its distinction between "Maq-like" and "end-to-end" modes. In
67 Bowtie 2 all alignments lie along a continuous spectrum of alignment
68 scores where the scoring scheme, similar to Needleman-Wunsch and
69 Smith-Waterman.
70
71 7. Bowtie 2's paired-end alignment is more flexible. E.g. for pairs
72 that do not align in a paired fashion, Bowtie 2 attempts to find
73 unpaired alignments for each mate.
74
75 8. Bowtie 2 reports a spectrum of mapping qualities, in contrast for
76 Bowtie 1 which reports either 0 or high.
77
78 9. Bowtie 2 does not align colorspace reads.
79
80 Bowtie 2 is not a "drop-in" replacement for Bowtie 1. Bowtie 2's
81 command-line arguments and genome index format are both different from
82 Bowtie 1's.
83
84 What isn't Bowtie 2?
85
86 Bowtie 2 is geared toward aligning relatively short sequencing reads to
87 long genomes. That said, it handles arbitrarily small reference
88 sequences (e.g. amplicons) and very long reads (i.e. upwards of 10s or
89 100s of kilobases), though it is slower in those settings. It is
90 optimized for the read lengths and error modes yielded by typical
91 Illumina sequencers.
92
93 Bowtie 2 does not support alignment of colorspace reads. (Bowtie 1
94 does.)
95
96 Obtaining Bowtie 2
97
98 Bowtie 2 is available from various package managers, notably Bioconda.
99 With Bioconda installed, you should be able to install Bowtie 2 with
100 conda install bowtie2.
101
102 You can also download Bowtie 2 sources and binaries from the Download
103 section of the Sourceforge site. Binaries are available for the x86_64
104 architecture running Linux, Mac OS X, and Windows. FreeBSD users can
105 obtain the latest version of Bowtie 2 from ports using
106 pkg install bowtie2. If you plan to compile Bowtie 2 yourself, make sure
107 to get the source package, i.e., the filename that ends in
108 "-source.zip".
109
110 Building from source
111
112 Building from source
113
114 Building Bowtie 2 from source requires a GNU-like environment with
115 Clang/GCC, GNU Make and other basics. It should be possible to build
116 Bowtie 2 on most vanilla *NIX installations or on a Mac installation
117 with Xcode installed. Bowtie 2 can also be built on Windows using a
118 64-bit MinGW distribution and MSYS. In order to simplify the MinGW setup
119 it might be worth investigating popular MinGW personal builds since
120 these are coming already prepared with most of the toolchains needed.
121
122 First, download the source package from the sourceforge site. Make sure
123 you're getting the source package; the file downloaded should end in
124 -source.zip. Unzip the file, change to the unzipped directory, and build
125 the Bowtie 2 tools by running GNU make (usually with the command make,
126 but sometimes with gmake) with no arguments. If building with MinGW, run
127 make from the MSYS environment.
128
129 The Bowtie 2 Makefile also includes recipes for basic automatic
130 dependency management. Running make static-libs && make STATIC_BUILD=1
131 will issue a series of commands that will: 1. download zstd and zlib 2.
132 compile them as static libraries 3. link the resulting libraries to the
133 compiled Bowtie 2 binaries
134
135 Building with SRA support
136
137 As of version 2.3.5 bowtie2 now supports aligning SRA reads. Prepackaged
138 builds will include a package that supports SRA. If you're building
139 bowtie2 from source please make sure that the Java runtime is available
140 on your system. You can then proceed with the build by running
141 make sra-deps && make USE_SRA=1.
142
143 Building with libsais support
144
145 As of version 2.5.3 bowtie2 supports building indexes using the SAIS
146 algorithm provided by libsais. SAIS is a state-of-the-art suffix array
147 construction algorithm that will bring-forth a significant speed-up to
148 the overall index building process. There is, however, the downside of a
149 significant increase in memory usage compared to the persistent
150 blockwise algorithm that bowtie2-build uses by default. When using SAIS
151 small indexes can be built for inputs up to 2GB. The bowtie2-build
152 wrapper will help determine the appropriate index type for uncompressed
153 and gzipped inputs.
154
155 To build bowtie2-build with libsais first make sure that the libsais
156 submodule is available. This can be done in one of the following ways:
157
158 - first time cloning bowtie2 --
159 git clone --recursive https://github.com/BenLangmead/bowtie2.git
160 - existing checkout of bowtie2 --
161 git submodule init && git submodule update
162
163 Issue the following command line to build libsais:
164
165 - with OpenMP support -- [g]make libsais USE_SAIS_OPENMP=1
166 - without OpenMP support -- [g]make libsais USE_SAIS=1
167
168 The choice of using OpenMP will determine whether or not the algorithm
169 runs multithreaded. The [-p/--threads] argument to bowtie2-build will be
170 ignored when libsais is compiled without OpenMP support.
171
172 Finally, building the bowtie2-build executable:
173
174 - with OpenMP support -- [g]make bowtie2-build-s USE_SAIS_OPENMP=1
175 - without OpenMP support -- [g]make bowtie2-build-s USE_SAIS=1
176
177 Building with CMake
178
179 To build Bowtie2 with SRA and libsais support issue the following
180 command:
181
182 - cmake . -D USE_SRA=1 -D USE_SAIS=1 && cmake --build .
183
184 CMake will take care of building and linking against the specified
185 dependencies.
186
187 Adding to PATH
188
189 By adding your new Bowtie 2 directory to your PATH environment variable,
190 you ensure that whenever you run bowtie2, bowtie2-build or
191 bowtie2-inspect from the command line, you will get the version you just
192 installed without having to specify the entire path. This is recommended
193 for most users. To do this, follow your operating system's instructions
194 for adding the directory to your PATH.
195
196 If you would like to install Bowtie 2 by copying the Bowtie 2 executable
197 files to an existing directory in your PATH, make sure that you copy all
198 the executables, including bowtie2, bowtie2-align-s, bowtie2-align-l,
199 bowtie2-build, bowtie2-build-s, bowtie2-build-l, bowtie2-inspect,
200 bowtie2-inspect-s and bowtie2-inspect-l.
201
202 The bowtie2 aligner
203
204 bowtie2 takes a Bowtie 2 index and a set of sequencing read files and
205 outputs a set of alignments in SAM format.
206
207 "Alignment" is the process by which we discover how and where the read
208 sequences are similar to the reference sequence. An "alignment" is a
209 result from this process, specifically: an alignment is a way of "lining
210 up" some or all of the characters in the read with some characters from
211 the reference in a way that reveals how they're similar. For example:
212
213 Read: GACTGGGCGATCTCGACTTCG
214 ||||| |||||||||| |||
215 Reference: GACTG--CGATCTCGACATCG
216
217 Where dash symbols represent gaps and vertical bars show where aligned
218 characters match.
219
220 We use alignment to make an educated guess as to where a read originated
221 with respect to the reference genome. It's not always possible to
222 determine this with certainty. For instance, if the reference genome
223 contains several long stretches of As (AAAAAAAAA etc.) and the read
224 sequence is a short stretch of As (AAAAAAA), we cannot know for certain
225 exactly where in the sea of As the read originated.
226
227 End-to-end alignment versus local alignment
228
229 By default, Bowtie 2 performs end-to-end read alignment. That is, it
230 searches for alignments involving all of the read characters. This is
231 also called an "untrimmed" or "unclipped" alignment.
232
233 When the --local option is specified, Bowtie 2 performs local read
234 alignment. In this mode, Bowtie 2 might "trim" or "clip" some read
235 characters from one or both ends of the alignment if doing so maximizes
236 the alignment score.
237
238 End-to-end alignment example
239
240 The following is an "end-to-end" alignment because it involves all the
241 characters in the read. Such an alignment can be produced by Bowtie 2 in
242 either end-to-end mode or in local mode.
243
244 Read: GACTGGGCGATCTCGACTTCG
245 Reference: GACTGCGATCTCGACATCG
246
247 Alignment:
248 Read: GACTGGGCGATCTCGACTTCG
249 ||||| |||||||||| |||
250 Reference: GACTG--CGATCTCGACATCG
251
252 Local alignment example
253
254 The following is a "local" alignment because some of the characters at
255 the ends of the read do not participate. In this case, 4 characters are
256 omitted (or "soft trimmed" or "soft clipped") from the beginning and 3
257 characters are omitted from the end. This sort of alignment can be
258 produced by Bowtie 2 only in local mode.
259
260 Read: ACGGTTGCGTTAATCCGCCACG
261 Reference: TAACTTGCGTTAAATCCGCCTGG
262
263 Alignment:
264 Read: ACGGTTGCGTTAA-TCCGCCACG
265 ||||||||| ||||||
266 Reference: TAACTTGCGTTAAATCCGCCTGG
267
268 Scores: higher = more similar
269
270 An alignment score quantifies how similar the read sequence is to the
271 reference sequence aligned to. The higher the score, the more similar
272 they are. A score is calculated by subtracting penalties for each
273 difference (mismatch, gap, etc.) and, in local alignment mode, adding
274 bonuses for each match.
275
276 The scores can be configured with the --ma (match bonus), --mp (mismatch
277 penalty), --np (penalty for having an N in either the read or the
278 reference), --rdg (affine read gap penalty) and --rfg (affine reference
279 gap penalty) options.
280
281 End-to-end alignment score example
282
283 A mismatched base at a high-quality position in the read receives a
284 penalty of -6 by default. A length-2 read gap receives a penalty of -11
285 by default (-5 for the gap open, -3 for the first extension, -3 for the
286 second extension). Thus, in end-to-end alignment mode, if the read is 50
287 bp long and it matches the reference exactly except for one mismatch at
288 a high-quality position and one length-2 read gap, then the overall
289 score is -(6 + 11) = -17.
290
291 The best possible alignment score in end-to-end mode is 0, which happens
292 when there are no differences between the read and the reference.
293
294 Local alignment score example
295
296 A mismatched base at a high-quality position in the read receives a
297 penalty of -6 by default. A length-2 read gap receives a penalty of -11
298 by default (-5 for the gap open, -3 for the first extension, -3 for the
299 second extension). A base that matches receives a bonus of +2 be
300 default. Thus, in local alignment mode, if the read is 50 bp long and it
301 matches the reference exactly except for one mismatch at a high-quality
302 position and one length-2 read gap, then the overall score equals the
303 total bonus, 2 * 49, minus the total penalty, 6 + 11, = 81.
304
305 The best possible score in local mode equals the match bonus times the
306 length of the read. This happens when there are no differences between
307 the read and the reference.
308
309 Valid alignments meet or exceed the minimum score threshold
310
311 For an alignment to be considered "valid" (i.e. "good enough") by Bowtie
312 2, it must have an alignment score no less than the minimum score
313 threshold. The threshold is configurable and is expressed as a function
314 of the read length. In end-to-end alignment mode, the default minimum
315 score threshold is -0.6 + -0.6 * L, where L is the read length. In local
316 alignment mode, the default minimum score threshold is 20 + 8.0 * ln(L),
317 where L is the read length. This can be configured with the --score-min
318 option. For details on how to set options like --score-min that
319 correspond to functions, see the section on setting function options.
320
321 Mapping quality: higher = more unique
322
323 The aligner cannot always assign a read to its point of origin with high
324 confidence. For instance, a read that originated inside a repeat element
325 might align equally well to many occurrences of the element throughout
326 the genome, leaving the aligner with no basis for preferring one over
327 the others.
328
329 Aligners characterize their degree of confidence in the point of origin
330 by reporting a mapping quality: a non-negative integer Q = -10 log10 p,
331 where p is an estimate of the probability that the alignment does not
332 correspond to the read's true point of origin. Mapping quality is
333 sometimes abbreviated MAPQ, and is recorded in the SAM MAPQ field.
334
335 Mapping quality is related to "uniqueness." We say an alignment is
336 unique if it has a much higher alignment score than all the other
337 possible alignments. The bigger the gap between the best alignment's
338 score and the second-best alignment's score, the more unique the best
339 alignment, and the higher its mapping quality should be.
340
341 Accurate mapping qualities are useful for downstream tools like variant
342 callers. For instance, a variant caller might choose to ignore evidence
343 from alignments with mapping quality less than, say, 10. A mapping
344 quality of 10 or less indicates that there is at least a 1 in 10 chance
345 that the read truly originated elsewhere.
346
347 Aligning pairs
348
349 A "paired-end" or "mate-pair" read consists of pair of mates, called
350 mate 1 and mate 2. Pairs come with a prior expectation about (a) the
351 relative orientation of the mates, and (b) the distance separating them
352 on the original DNA molecule. Exactly what expectations hold for a given
353 dataset depends on the lab procedures used to generate the data. For
354 example, a common lab procedure for producing pairs is Illumina's
355 Paired-end Sequencing Assay, which yields pairs with a relative
356 orientation of FR ("forward, reverse") meaning that if mate 1 came from
357 the Watson strand, mate 2 very likely came from the Crick strand and
358 vice versa. Also, this protocol yields pairs where the expected genomic
359 distance from end to end is about 200-500 base pairs.
360
361 For simplicity, this manual uses the term "paired-end" to refer to any
362 pair of reads with some expected relative orientation and distance.
363 Depending on the protocol, these might actually be referred to as
364 "paired-end" or "mate-paired." Also, we always refer to the individual
365 sequences making up the pair as "mates."
366
367 Paired inputs
368
369 Pairs are often stored in a pair of files, one file containing the mate
370 1s and the other containing the mates 2s. The first mate in the file for
371 mate 1 forms a pair with the first mate in the file for mate 2, the
372 second with the second, and so on. When aligning pairs with Bowtie 2,
373 specify the file with the mate 1s mates using the -1 argument and the
374 file with the mate 2s using the -2 argument. This causes Bowtie 2 to
375 take the paired nature of the reads into account when aligning them.
376
377 Paired SAM output
378
379 When Bowtie 2 prints a SAM alignment for a pair, it prints two records
380 (i.e. two lines of output), one for each mate. The first record
381 describes the alignment for mate 1 and the second record describes the
382 alignment for mate 2. In both records, some of the fields of the SAM
383 record describe various properties of the alignment; for instance, the
384 7th and 8th fields (RNEXT and PNEXT respectively) indicate the reference
385 name and position where the other mate aligned, and the 9th field
386 indicates the inferred length of the DNA fragment from which the two
387 mates were sequenced. See the SAM specification for more details
388 regarding these fields.
389
390 Concordant pairs match pair expectations, discordant pairs don't
391
392 A pair that aligns with the expected relative mate orientation and with
393 the expected range of distances between mates is said to align
394 "concordantly". If both mates have unique alignments, but the alignments
395 do not match paired-end expectations (i.e. the mates aren't in the
396 expected relative orientation, or aren't within the expected distance
397 range, or both), the pair is said to align "discordantly". Discordant
398 alignments may be of particular interest, for instance, when seeking
399 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
404 distance") is set with the -I and -X options. Note that setting -I and
405 -X far apart makes Bowtie 2 slower. See documentation for -I and -X.
406
407 To declare that a pair aligns discordantly, Bowtie 2 requires that both
408 mates align uniquely. This is a conservative threshold, but this is
409 often desirable when seeking structural variants.
410
411 By default, Bowtie 2 searches for both concordant and discordant
412 alignments, though searching for discordant alignments can be disabled
413 with the --no-discordant option.
414
415 Mixed mode: paired where possible, unpaired otherwise
416
417 If Bowtie 2 cannot find a paired-end alignment for a pair, by default it
418 will go on to look for unpaired alignments for the constituent mates.
419 This is called "mixed mode." To disable mixed mode, set the --no-mixed
420 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
428 that describe the paired-end nature of the read and alignment. The first
429 (least significant) bit (1 in decimal, 0x1 in hexadecimal) is set if the
430 read is part of a pair. The second bit (2 in decimal, 0x2 in
431 hexadecimal) is set if the read is part of a pair that aligned in a
432 paired-end fashion. The fourth bit (8 in decimal, 0x8 in hexadecimal) is
433 set if the read is part of a pair and the other mate in the pair had at
434 least one valid alignment. The sixth bit (32 in decimal, 0x20 in
435 hexadecimal) is set if the read is part of a pair and the other mate in
436 the pair aligned to the Crick strand (or, equivalently, if the reverse
437 complement of the other mate aligned to the Watson strand). The seventh
438 bit (64 in decimal, 0x40 in hexadecimal) is set if the read is mate 1 in
439 a pair. The eighth bit (128 in decimal, 0x80 in hexadecimal) is set if
440 the read is mate 2 in a pair. See the SAM specification for a more
441 detailed description of the FLAGS field.
442
443 Some SAM optional fields describe more paired-end properties
444
445 The last several fields of each SAM record usually contain SAM optional
446 fields, which are simply tab-separated strings conveying additional
447 information about the reads and alignments. A SAM optional field is
448 formatted like this: "XP:i:1" where "XP" is the TAG, "i" is the TYPE
449 ("integer" in this case), and "1" is the VALUE. See the SAM
450 specification for details regarding SAM optional fields.
451
452 Mates can overlap, contain, or dovetail each other
453
454 The fragment and read lengths might be such that alignments for the two
455 mates from a pair overlap each other. Consider this example:
456
457 (For these examples, assume we expect mate 1 to align to the left of
458 mate 2.)
459
460 Mate 1: GCAGATTATATGAGTCAGCTACGATATTGTT
461 Mate 2: TGTTTGGGGTGACACATTACGCGTCTTTGAC
462 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
463
464 It's also possible, though unusual, for one mate alignment to contain
465 the other, as in these examples:
466
467 Mate 1: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGC
468 Mate 2: TGTTTGGGGTGACACATTACGC
469 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
470
471 Mate 1: CAGCTACGATATTGTTTGGGGTGACACATTACGC
472 Mate 2: CTACGATATTGTTTGGGGTGAC
473 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
474
475 And it's also possible, though unusual, for the mates to "dovetail",
476 with the mates seemingly extending "past" each other as in this example:
477
478 Mate 1: GTCAGCTACGATATTGTTTGGGGTGACACATTACGC
479 Mate 2: TATGAGTCAGCTACGATATTGTTTGGGGTGACACAT
480 Reference: GCAGATTATATGAGTCAGCTACGATATTGTTTGGGGTGACACATTACGCGTCTTTGAC
481
482 In some situations, it's desirable for the aligner to consider all these
483 cases as "concordant" as long as other paired-end constraints are not
484 violated. Bowtie 2's default behavior is to consider overlapping and
485 containing as being consistent with concordant alignment. By default,
486 dovetailing is considered inconsistent with concordant alignment.
487
488 These defaults can be overridden. Setting --no-overlap causes Bowtie 2
489 to consider overlapping mates as non-concordant. Setting --no-contain
490 causes Bowtie 2 to consider cases where one mate alignment contains the
491 other as non-concordant. Setting --dovetail causes Bowtie 2 to consider
492 cases where the mate alignments dovetail as concordant.
493
494 Reporting
495
496 The reporting mode governs how many alignments Bowtie 2 looks for, and
497 how to report them. Bowtie 2 has three distinct reporting modes. The
498 default reporting mode is similar to the default reporting mode of many
499 other read alignment tools, including BWA. It is also similar to Bowtie
500 1's -M alignment mode.
501
502 In general, when we say that a read has an alignment, we mean that it
503 has a valid alignment. When we say that a read has multiple alignments,
504 we mean that it has multiple alignments that are valid and distinct from
505 one another.
506
507 Distinct alignments map a read to different places
508
509 Two alignments for the same individual read are "distinct" if they map
510 the same read to different places. Specifically, we say that two
511 alignments are distinct if there are no alignment positions where a
512 particular read offset is aligned opposite a particular reference offset
513 in both alignments with the same orientation. E.g. if the first
514 alignment is in the forward orientation and aligns the read character at
515 read offset 10 to the reference character at chromosome 3, offset
516 3,445,245, and the second alignment is also in the forward orientation
517 and also aligns the read character at read offset 10 to the reference
518 character at chromosome 3, offset 3,445,245, they are not distinct
519 alignments.
520
521 Two alignments for the same pair are distinct if either the mate 1s in
522 the two paired-end alignments are distinct or the mate 2s in the two
523 alignments are distinct or both.
524
525 Default mode: search for multiple alignments, report the best one
526
527 By default, Bowtie 2 searches for distinct, valid alignments for each
528 read. When it finds a valid alignment, it generally will continue to
529 look for alignments that are nearly as good or better. It will
530 eventually stop looking, either because it exceeded a limit placed on
531 search effort (see -D and -R) or because it already knows all it needs
532 to know to report an alignment. Information from the best alignments are
533 used to estimate mapping quality (the MAPQ SAM field) and to set SAM
534 optional fields, such as AS:i and XS:i. Bowtie 2 does not guarantee that
535 the alignment reported is the best possible in terms of alignment score.
536
537 See also: -D, which puts an upper limit on the number of dynamic
538 programming problems (i.e. seed extensions) that can "fail" in a row
539 before Bowtie 2 stops searching. Increasing -D makes Bowtie 2 slower,
540 but increases the likelihood that it will report the correct alignment
541 for a read that aligns many places.
542
543 See also: -R, which sets the maximum number of times Bowtie 2 will
544 "re-seed" when attempting to align a read with repetitive seeds.
545 Increasing -R makes Bowtie 2 slower, but increases the likelihood that
546 it will report the correct alignment for a read that aligns many places.
547
548 -k mode: search for one or more alignments, report each
549
550 In -k mode, Bowtie 2 searches for up to N distinct, valid alignments for
551 each read, where N equals the integer specified with the -k parameter.
552 That is, if -k 2 is specified, Bowtie 2 will search for at most 2
553 distinct alignments. It reports all alignments found, in descending
554 order by alignment score. The alignment score for a paired-end alignment
555 equals the sum of the alignment scores of the individual mates. Each
556 reported read or pair alignment beyond the first has the SAM 'secondary'
557 bit (which equals 256) set in its FLAGS field. Supplementary alignments
558 will also be assigned a MAPQ of 255. See the SAM specification for
559 details.
560
561 Bowtie 2 does not "find" alignments in any specific order, so for reads
562 that have more than N distinct, valid alignments, Bowtie 2 does not
563 guarantee that the N alignments reported are the best possible in terms
564 of alignment score. Still, this mode can be effective and fast in
565 situations where the user cares more about whether a read aligns (or
566 aligns a certain number of times) than where exactly it originated.
567
568 -a mode: search for and report all alignments
569
570 -a mode is similar to -k mode except that there is no upper limit on the
571 number of alignments Bowtie 2 should report. Alignments are reported in
572 descending order by alignment score. The alignment score for a
573 paired-end alignment equals the sum of the alignment scores of the
574 individual mates. Each reported read or pair alignment beyond the first
575 has the SAM 'secondary' bit (which equals 256) set in its FLAGS field.
576 Supplementary alignments will be assigned a MAPQ of 255. See the SAM
577 specification for details.
578
579 Some tools are designed with this reporting mode in mind. Bowtie 2 is
580 not! For very large genomes, this mode is very slow.
581
582 Randomness in Bowtie 2
583
584 Bowtie 2's search for alignments for a given read is "randomized." That
585 is, when Bowtie 2 encounters a set of equally-good choices, it uses a
586 pseudo-random number to choose. For example, if Bowtie 2 discovers a set
587 of 3 equally-good alignments and wants to decide which to report, it
588 picks a pseudo-random integer 0, 1 or 2 and reports the corresponding
589 alignment. Arbitrary choices can crop up at various points during
590 alignment.
591
592 The pseudo-random number generator is re-initialized for every read, and
593 the seed used to initialize it is a function of the read name,
594 nucleotide string, quality string, and the value specified with --seed.
595 If you run the same version of Bowtie 2 on two reads with identical
596 names, nucleotide strings, and quality strings, and if --seed is set the
597 same for both runs, Bowtie 2 will produce the same output; i.e., it will
598 align the read to the same place, even if there are multiple equally
599 good alignments. This is intuitive and desirable in most cases. Most
600 users expect Bowtie to produce the same output when run twice on the
601 same input.
602
603 However, when the user specifies the --non-deterministic option, Bowtie
604 2 will use the current time to re-initialize the pseudo-random number
605 generator. When this is specified, Bowtie 2 might report different
606 alignments for identical reads. This is counter-intuitive for some
607 users, but might be more appropriate in situations where the input
608 consists of many identical reads.
609
610 Multiseed heuristic
611
612 To rapidly narrow the number of possible alignments that must be
613 considered, Bowtie 2 begins by extracting substrings ("seeds") from the
614 read and its reverse complement and aligning them in an ungapped fashion
615 with the help of the FM Index. This is "multiseed alignment" and it is
616 similar to what Bowtie 1 does, except Bowtie 1 attempts to align the
617 entire read this way.
618
619 This initial step makes Bowtie 2 much faster than it would be without
620 such a filter, but at the expense of missing some valid alignments. For
621 instance, it is possible for a read to have a valid overall alignment
622 but to have no valid seed alignments because each potential seed
623 alignment is interrupted by too many mismatches or gaps.
624
625 The trade-off between speed and sensitivity/accuracy can be adjusted by
626 setting the seed length (-L), the interval between extracted seeds (-i),
627 and the number of mismatches permitted per seed (-N). For more sensitive
628 alignment, set these parameters to (a) make the seeds closer together,
629 (b) make the seeds shorter, and/or (c) allow more mismatches. You can
630 adjust these options one-by-one, though Bowtie 2 comes with some useful
631 combinations of options prepackaged as "preset options."
632
633 -D and -R are also options that adjust the trade-off between speed and
634 sensitivity/accuracy.
635
636 FM Index memory footprint
637
638 Bowtie 2 uses the FM Index to find ungapped alignments for seeds. This
639 step accounts for the bulk of Bowtie 2's memory footprint, as the FM
640 Index itself is typically the largest data structure used. For instance,
641 the memory footprint of the FM Index for the human genome is about 3.2
642 gigabytes of RAM.
643
644 Ambiguous characters
645
646 Non-whitespace characters besides A, C, G or T are considered
647 "ambiguous." N is a common ambiguous character that appears in reference
648 sequences. Bowtie 2 considers all ambiguous characters in the reference
649 (including IUPAC nucleotide codes) to be Ns.
650
651 Bowtie 2 allows alignments to overlap ambiguous characters in the
652 reference. An alignment position that contains an ambiguous character in
653 the read, reference, or both, is penalized according to --np. --n-ceil
654 sets an upper limit on the number of positions that may contain
655 ambiguous reference characters in a valid alignment. The optional field
656 XN:i reports the number of ambiguous reference characters overlapped by
657 an alignment.
658
659 Note that the multiseed heuristic cannot find seed alignments that
660 overlap ambiguous reference characters. For an alignment overlapping an
661 ambiguous reference character to be found, it must have one or more seed
662 alignments that do not overlap ambiguous reference characters.
663
664 Presets: setting many settings at once
665
666 Bowtie 2 comes with some useful combinations of parameters packaged into
667 shorter "preset" parameters. For example, running Bowtie 2 with the
668 --very-sensitive option is the same as running with options:
669 -D 20 -R 3 -N 0 -L 20 -i S,1,0.50. The preset options that come with
670 Bowtie 2 are designed to cover a wide area of the
671 speed/sensitivity/accuracy trade-off space, with the presets ending in
672 fast generally being faster but less sensitive and less accurate, and
673 the presets ending in sensitive generally being slower but more
674 sensitive and more accurate. See the documentation for the preset
675 options for details.
676
677 As of Bowtie2 v2.4.0, individual preset values can be overridden by
678 providing the specific options e.g. the configured seed length of 20 in
679 the [--very-senitive] preset above can be changed to 25 by also
680 specifying the -L 25 parameter anywhere on the command line.
681
682 Filtering
683
684 Some reads are skipped or "filtered out" by Bowtie 2. For example, reads
685 may be filtered out because they are extremely short or have a high
686 proportion of ambiguous nucleotides. Bowtie 2 will still print a SAM
687 record for such a read, but no alignment will be reported and the YF:i
688 SAM optional field will be set to indicate the reason the read was
689 filtered.
690
691 - YF:Z:LN: the read was filtered because it had length less than or
692 equal to the number of seed mismatches set with the -N option.
693 - YF:Z:NS: the read was filtered because it contains a number of
694 ambiguous characters (usually N or .) greater than the ceiling
695 specified with --n-ceil.
696 - YF:Z:SC: the read was filtered because the read length and the match
697 bonus (set with --ma) are such that the read can't possibly earn an
698 alignment score greater than or equal to the threshold set with
699 --score-min
700 - YF:Z:QC: the read was filtered because it was marked as failing
701 quality control and the user specified the --qc-filter option. This
702 only happens when the input is in Illumina's QSEQ format (i.e. when
703 --qseq is specified) and the last (11th) field of the read's QSEQ
704 record contains 1.
705
706 If a read could be filtered for more than one reason, the value YF:Z
707 flag will reflect only one of those reasons.
708
709 Alignment summary
710
711 When Bowtie 2 finishes running, it prints messages summarizing what
712 happened. These messages are printed to the "standard error" ("stderr")
713 filehandle. For datasets consisting of unpaired reads, the summary might
714 look like this:
715
716 20000 reads; of these:
717 20000 (100.00%) were unpaired; of these:
718 1247 (6.24%) aligned 0 times
719 18739 (93.69%) aligned exactly 1 time
720 14 (0.07%) aligned >1 times
721 93.77% overall alignment rate
722
723 For datasets consisting of pairs, the summary might look like this:
724
725 10000 reads; of these:
726 10000 (100.00%) were paired; of these:
727 650 (6.50%) aligned concordantly 0 times
728 8823 (88.23%) aligned concordantly exactly 1 time
729 527 (5.27%) aligned concordantly >1 times
730 ----
731 650 pairs aligned concordantly 0 times; of these:
732 34 (5.23%) aligned discordantly 1 time
733 ----
734 616 pairs aligned 0 times concordantly or discordantly; of these:
735 1232 mates make up the pairs; of these:
736 660 (53.57%) aligned 0 times
737 571 (46.35%) aligned exactly 1 time
738 1 (0.08%) aligned >1 times
739 96.70% overall alignment rate
740
741 The indentation indicates how subtotals relate to totals.
742
743 Wrapper scripts
744
745 The bowtie2, bowtie2-build and bowtie2-inspect executables are actually
746 wrapper scripts that call binary programs as appropriate. The wrappers
747 shield users from having to distinguish between "small" and "large"
748 index formats, discussed briefly in the following section. Also, the
749 bowtie2 wrapper provides some key functionality, like the ability to
750 handle compressed inputs, and the functionality for --un, --al and
751 related options.
752
753 It is recommended that you always run the bowtie2 wrappers and not run
754 the binaries directly.
755
756 Small and large indexes
757
758 bowtie2-build can index reference genomes of any size. For genomes less
759 than about 4 billion nucleotides in length, bowtie2-build builds a
760 "small" index using 32-bit numbers in various parts of the index. When
761 the genome is longer, bowtie2-build builds a "large" index using 64-bit
762 numbers. Small indexes are stored in files with the .bt2 extension, and
763 large indexes are stored in files with the .bt2l extension. The user
764 need not worry about whether a particular index is small or large; the
765 wrapper scripts will automatically build and use the appropriate index.
766
767 Performance tuning
768
769 1. If your computer has multiple processors/cores, use -p
770
771 The -p option causes Bowtie 2 to launch a specified number of
772 parallel search threads. Each thread runs on a different
773 processor/core and all threads find alignments in parallel,
774 increasing alignment throughput by approximately a multiple of the
775 number of threads (though in practice, speedup is somewhat worse
776 than linear).
777
778 2. If reporting many alignments per read, try reducing
779 bowtie2-build --offrate
780
781 If you are using -k or -a options and Bowtie 2 is reporting many
782 alignments per read, using an index with a denser SA sample can
783 speed things up considerably. To do this, specify a
784 smaller-than-default -o/--offrate value when running bowtie2-build.
785 A denser SA sample yields a larger index, but is also particularly
786 effective at speeding up alignment when many alignments are reported
787 per read.
788
789 3. If bowtie2 "thrashes", try increasing bowtie2-build --offrate
790
791 If bowtie2 runs very slowly on a relatively low-memory computer, try
792 setting -o/--offrate to a larger value when building the index. This
793 decreases the memory footprint of the index.
794
795 Command Line
796
797 Setting function options
798
799 Some Bowtie 2 options specify a function rather than an individual
800 number or setting. In these cases the user specifies three parameters:
801 (a) a function type F, (b) a constant term B, and (c) a coefficient A.
802 The available function types are constant (C), linear (L), square-root
803 (S), and natural log (G). The parameters are specified as F,B,A - that
804 is, the function type, the constant term, and the coefficient are
805 separated by commas with no whitespace. The constant term and
806 coefficient may be negative and/or floating-point numbers.
807
808 For example, if the function specification is L,-0.4,-0.6, then the
809 function defined is:
810
811 f(x) = -0.4 + -0.6 * x
812
813 If the function specification is G,1,5.4, then the function defined is:
814
815 f(x) = 1.0 + 5.4 * ln(x)
816
817 See the documentation for the option in question to learn what the
818 parameter x is for. For example, in the case if the --score-min option,
819 the function f(x) sets the minimum alignment score necessary for an
820 alignment to be considered valid, and x is the read length.
821
822 Usage
823
824 bowtie2 [options]* -x <bt2-idx> {-1 <m1> -2 <m2> | -U <r> | --interleaved <i> | --sra-acc <acc> | -b <bam>} -S [<sam>]
825
826 Main arguments
827
828 -x <bt2-idx>
829
830 The basename of the index for the reference genome. The basename is the
831 name of any of the index files up to but not including the final .1.bt2
832 / .rev.1.bt2 / etc. bowtie2 looks for the specified index first in the
833 current directory, then in the directory specified in the
834 BOWTIE2_INDEXES environment variable.
835
836 -1 <m1>
837
838 Comma-separated list of files containing mate 1s (filename usually
839 includes _1), e.g. -1 flyA_1.fq,flyB_1.fq. Sequences specified with this
840 option must correspond file-for-file and read-for-read with those
841 specified in <m2>. Reads may be a mix of different lengths. If - is
842 specified, bowtie2 will read the mate 1s from the "standard in" or
843 "stdin" filehandle.
844
845 -2 <m2>
846
847 Comma-separated list of files containing mate 2s (filename usually
848 includes _2), e.g. -2 flyA_2.fq,flyB_2.fq. Sequences specified with this
849 option must correspond file-for-file and read-for-read with those
850 specified in <m1>. Reads may be a mix of different lengths. If - is
851 specified, bowtie2 will read the mate 2s from the "standard in" or
852 "stdin" filehandle.
853
854 -U <r>
855
856 Comma-separated list of files containing unpaired reads to be aligned,
857 e.g. lane1.fq,lane2.fq,lane3.fq,lane4.fq. Reads may be a mix of
858 different lengths. If - is specified, bowtie2 gets the reads from the
859 "standard in" or "stdin" filehandle.
860
861 --interleaved
862
863 Reads interleaved FASTQ files where the first two records (8 lines)
864 represent a mate pair.
865
866 --sra-acc
867
868 Reads are SRA accessions. If the accession provided cannot be found in
869 local storage it will be fetched from the NCBI database. If you find
870 that SRA alignments are long running please rerun your command with the
871 -p/--threads parameter set to desired number of threads.
872
873 NB: this option is only available if bowtie 2 is compiled with the
874 necessary SRA libraries. See Obtaining Bowtie 2 for details.
875
876 -b <bam>
877
878 Reads are unaligned BAM records sorted by read name. The
879 --align-paired-reads and --preserve-tags options affect the way Bowtie 2
880 processes records.
881
882 -S <sam>
883
884 File to write SAM alignments to. By default, alignments are written to
885 the "standard out" or "stdout" filehandle (i.e. the console).
886
887 Options
888
889 Input options
890
891 -q
892
893 Reads (specified with <m1>, <m2>, <s>) are FASTQ files. FASTQ files
894 usually have extension .fq or .fastq. FASTQ is the default format. See
895 also: --solexa-quals and --int-quals.
896
897 --tab5
898
899 Each read or pair is on a single line. An unpaired read line is
900 [name]\t[seq]\t[qual]\n. A paired-end read line is
901 [name]\t[seq1]\t[qual1]\t[seq2]\t[qual2]\n. An input file can be a mix
902 of unpaired and paired-end reads and Bowtie 2 recognizes each according
903 to the number of fields, handling each as it should.
904
905 --tab6
906
907 Similar to --tab5 except, for paired-end reads, the second end can have
908 a different name from the first:
909 [name1]\t[seq1]\t[qual1]\t[name2]\t[seq2]\t[qual2]\n
910
911 --qseq
912
913 Reads (specified with <m1>, <m2>, <s>) are QSEQ files. QSEQ files
914 usually end in _qseq.txt. See also: --solexa-quals and --int-quals.
915
916 -f
917
918 Reads (specified with <m1>, <m2>, <s>) are FASTA files. FASTA files
919 usually have extension .fa, .fasta, .mfa, .fna or similar. FASTA files
920 do not have a way of specifying quality values, so when -f is set, the
921 result is as if --ignore-quals is also set.
922
923 -r
924
925 Reads (specified with <m1>, <m2>, <s>) are files with one input sequence
926 per line, without any other information (no read names, no qualities).
927 When -r is set, the result is as if --ignore-quals is also set.
928
929 -F k:<int>,i:<int>
930
931 Reads are substrings (k-mers) extracted from a FASTA file. Specifically,
932 for every reference sequence in the FASTA file, Bowtie 2 aligns the
933 k-mers at offsets 1, 1+i, 1+2i, ... until reaching the end of the
934 reference. Each k-mer is aligned as a separate read. Quality values are
935 set to all Is (40 on Phred scale). Each k-mer (read) is given a name
936 like <sequence>_<offset>, where <sequence> is the name of the FASTA
937 sequence it was drawn from and <offset> is its 0-based offset of origin
938 with respect to the sequence. Only single k-mers, i.e. unpaired reads,
939 can be aligned in this way.
940 -c
941
942 The read sequences are given on command line. I.e. <m1>, <m2> and
943 <singles> are comma-separated lists of reads rather than lists of read
944 files. There is no way to specify read names or qualities, so -c also
945 implies --ignore-quals.
946
947 -s/--skip <int>
948
949 Skip (i.e. do not align) the first <int> reads or pairs in the input.
950
951 -u/--qupto <int>
952
953 Align the first <int> reads or read pairs from the input (after the
954 -s/--skip reads or pairs have been skipped), then stop. Default: no
955 limit.
956
957 -5/--trim5 <int>
958
959 Trim <int> bases from 5' (left) end of each read before alignment
960 (default: 0).
961
962 -3/--trim3 <int>
963
964 Trim <int> bases from 3' (right) end of each read before alignment
965 (default: 0).
966
967 --trim-to [3:|5:]<int>
968
969 Trim reads exceeding <int> bases. Bases will be trimmed from either the
970 3' (right) or 5' (left) end of the read. If the read end if not
971 specified, bowtie 2 will default to trimming from the 3' (right) end of
972 the read. --trim-to and -3/-5 are mutually exclusive.
973
974 --phred33
975
976 Input qualities are ASCII chars equal to the Phred quality plus 33. This
977 is also called the "Phred+33" encoding, which is used by the very latest
978 Illumina pipelines.
979
980 --phred64
981
982 Input qualities are ASCII chars equal to the Phred quality plus 64. This
983 is also called the "Phred+64" encoding.
984
985 --solexa-quals
986
987 Convert input qualities from Solexa (which can be negative) to Phred
988 (which can't). This scheme was used in older Illumina GA Pipeline
989 versions (prior to 1.3). Default: off.
990
991 --int-quals
992
993 Quality values are represented in the read input file as space-separated
994 ASCII integers, e.g., 40 40 30 40..., rather than ASCII characters,
995 e.g., II?I.... Integers are treated as being on the Phred quality scale
996 unless --solexa-quals is also specified. Default: off.
997
998 Preset options in --end-to-end mode
999
1000 --very-fast
1001
1002 Same as: -D 5 -R 1 -N 0 -L 22 -i S,0,2.50
1003
1004 --fast
1005
1006 Same as: -D 10 -R 2 -N 0 -L 22 -i S,0,2.50
1007
1008 --sensitive
1009
1010 Same as: -D 15 -R 2 -N 0 -L 22 -i S,1,1.15 (default in --end-to-end
1011 mode)
1012
1013 --very-sensitive
1014
1015 Same as: -D 20 -R 3 -N 0 -L 20 -i S,1,0.50
1016
1017 Preset options in --local mode
1018
1019 --very-fast-local
1020
1021 Same as: -D 5 -R 1 -N 0 -L 25 -i S,1,2.00
1022
1023 --fast-local
1024
1025 Same as: -D 10 -R 2 -N 0 -L 22 -i S,1,1.75
1026
1027 --sensitive-local
1028
1029 Same as: -D 15 -R 2 -N 0 -L 20 -i S,1,0.75 (default in --local mode)
1030
1031 --very-sensitive-local
1032
1033 Same as: -D 20 -R 3 -N 0 -L 20 -i S,1,0.50
1034
1035 Alignment options
1036
1037 -N <int>
1038
1039 Sets the number of mismatches to allowed in a seed alignment during
1040 multiseed alignment. Can be set to 0 or 1. Setting this higher makes
1041 alignment slower (often much slower) but increases sensitivity. Default:
1042 0.
1043
1044 -L <int>
1045
1046 Sets the length of the seed substrings to align during multiseed
1047 alignment. Smaller values make alignment slower but more sensitive.
1048 Default: the --sensitive preset is used by default, which sets -L to 22
1049 and 20 in --end-to-end mode and in --local mode.
1050
1051 -i <func>
1052
1053 Sets a function governing the interval between seed substrings to use
1054 during multiseed alignment. For instance, if the read has 30 characters,
1055 and seed length is 10, and the seed interval is 6, the seeds extracted
1056 will be:
1057
1058 Read: TAGCTACGCTCTACGCTATCATGCATAAAC
1059 Seed 1 fw: TAGCTACGCT
1060 Seed 1 rc: AGCGTAGCTA
1061 Seed 2 fw: CGCTCTACGC
1062 Seed 2 rc: GCGTAGAGCG
1063 Seed 3 fw: ACGCTATCAT
1064 Seed 3 rc: ATGATAGCGT
1065 Seed 4 fw: TCATGCATAA
1066 Seed 4 rc: TTATGCATGA
1067
1068 Since it's best to use longer intervals for longer reads, this parameter
1069 sets the interval as a function of the read length, rather than a single
1070 one-size-fits-all number. For instance, specifying -i S,1,2.5 sets the
1071 interval function f to f(x) = 1 + 2.5 * sqrt(x), where x is the read
1072 length. See also: setting function options. If the function returns a
1073 result less than 1, it is rounded up to 1. Default: the --sensitive
1074 preset is used by default, which sets -i to S,1,1.15 in --end-to-end
1075 mode to -i S,1,0.75 in --local mode.
1076
1077 --n-ceil <func>
1078
1079 Sets a function governing the maximum number of ambiguous characters
1080 (usually Ns and/or .s) allowed in a read as a function of read length.
1081 For instance, specifying -L,0,0.15 sets the N-ceiling function f to
1082 f(x) = 0 + 0.15 * x, where x is the read length. See also: setting
1083 function options. Reads exceeding this ceiling are filtered out.
1084 Default: L,0,0.15.
1085
1086 --dpad <int>
1087
1088 "Pads" dynamic programming problems by <int> columns on either side to
1089 allow gaps. Default: 15.
1090
1091 --gbar <int>
1092
1093 Disallow gaps within <int> positions of the beginning or end of the
1094 read. Default: 4.
1095
1096 --ignore-quals
1097
1098 When calculating a mismatch penalty, always consider the quality value
1099 at the mismatched position to be the highest possible, regardless of the
1100 actual value. I.e. input is treated as though all quality values are
1101 high. This is also the default behavior when the input doesn't specify
1102 quality values (e.g. in -f, -r, or -c modes).
1103
1104 --nofw/--norc
1105
1106 If --nofw is specified, bowtie2 will not attempt to align unpaired reads
1107 to the forward (Watson) reference strand. If --norc is specified,
1108 bowtie2 will not attempt to align unpaired reads against the
1109 reverse-complement (Crick) reference strand. In paired-end mode, --nofw
1110 and --norc pertain to the fragments; i.e. specifying --nofw causes
1111 bowtie2 to explore only those paired-end configurations corresponding to
1112 fragments from the reverse-complement (Crick) strand. Default: both
1113 strands enabled.
1114
1115 --no-1mm-upfront
1116
1117 By default, Bowtie 2 will attempt to find either an exact or a
1118 1-mismatch end-to-end alignment for the read before trying the multiseed
1119 heuristic. Such alignments can be found very quickly, and many short
1120 read alignments have exact or near-exact end-to-end alignments. However,
1121 this can lead to unexpected alignments when the user also sets options
1122 governing the multiseed heuristic, like -L and -N. For instance, if the
1123 user specifies -N 0 and -L equal to the length of the read, the user
1124 will be surprised to find 1-mismatch alignments reported. This option
1125 prevents Bowtie 2 from searching for 1-mismatch end-to-end alignments
1126 before using the multiseed heuristic, which leads to the expected
1127 behavior when combined with options such as -L and -N. This comes at the
1128 expense of speed.
1129
1130 --end-to-end
1131
1132 In this mode, Bowtie 2 requires that the entire read align from one end
1133 to the other, without any trimming (or "soft clipping") of characters
1134 from either end. The match bonus --ma always equals 0 in this mode, so
1135 all alignment scores are less than or equal to 0, and the greatest
1136 possible alignment score is 0. This is mutually exclusive with --local.
1137 --end-to-end is the default mode.
1138
1139 --local
1140
1141 In this mode, Bowtie 2 does not require that the entire read align from
1142 one end to the other. Rather, some characters may be omitted ("soft
1143 clipped") from the ends in order to achieve the greatest possible
1144 alignment score. The match bonus --ma is used in this mode, and the best
1145 possible alignment score is equal to the match bonus (--ma) times the
1146 length of the read. Specifying --local and one of the presets (e.g.
1147 --local --very-fast) is equivalent to specifying the local version of
1148 the preset (--very-fast-local). This is mutually exclusive with
1149 --end-to-end. --end-to-end is the default mode.
1150
1151 Scoring options
1152
1153 --ma <int>
1154
1155 Sets the match bonus. In --local mode <int> is added to the alignment
1156 score for each position where a read character aligns to a reference
1157 character and the characters match. Not used in --end-to-end mode.
1158 Default: 2.
1159
1160 --mp MX,MN
1161
1162 Sets the maximum (MX) and minimum (MN) mismatch penalties, both
1163 integers. A number less than or equal to MX and greater than or equal to
1164 MN is subtracted from the alignment score for each position where a read
1165 character aligns to a reference character, the characters do not match,
1166 and neither is an N. If --ignore-quals is specified, the number
1167 subtracted quals MX. Otherwise, the number subtracted is
1168 MN + floor( (MX-MN)(MIN(Q, 40.0)/40.0) ) where Q is the Phred quality
1169 value. Default: MX = 6, MN = 2.
1170
1171 --np <int>
1172
1173 Sets penalty for positions where the read, reference, or both, contain
1174 an ambiguous character such as N. Default: 1.
1175
1176 --rdg <int1>,<int2>
1177
1178 Sets the read gap open (<int1>) and extend (<int2>) penalties. A read
1179 gap of length N gets a penalty of <int1> + N * <int2>. Default: 5, 3.
1180
1181 --rfg <int1>,<int2>
1182
1183 Sets the reference gap open (<int1>) and extend (<int2>) penalties. A
1184 reference gap of length N gets a penalty of <int1> + N * <int2>.
1185 Default: 5, 3.
1186
1187 --score-min <func>
1188
1189 Sets a function governing the minimum alignment score needed for an
1190 alignment to be considered "valid" (i.e. good enough to report). This is
1191 a function of read length. For instance, specifying L,0,-0.6 sets the
1192 minimum-score function f to f(x) = 0 + -0.6 * x, where x is the read
1193 length. See also: setting function options. The default in --end-to-end
1194 mode is L,-0.6,-0.6 and the default in --local mode is G,20,8.
1195
1196 Reporting options
1197
1198 -k <int>
1199
1200 By default, bowtie2 searches for distinct, valid alignments for each
1201 read. When it finds a valid alignment, it continues looking for
1202 alignments that are nearly as good or better. The best alignment found
1203 is reported (randomly selected from among best if tied). Information
1204 about the best alignments is used to estimate mapping quality and to set
1205 SAM optional fields, such as AS:i and XS:i.
1206
1207 When -k is specified, however, bowtie2 behaves differently. Instead, it
1208 searches for at most <int> distinct, valid alignments for each read. The
1209 search terminates when it can't find more distinct valid alignments, or
1210 when it finds <int>, whichever happens first. All alignments found are
1211 reported in descending order by alignment score. The alignment score for
1212 a paired-end alignment equals the sum of the alignment scores of the
1213 individual mates. Each reported read or pair alignment beyond the first
1214 has the SAM 'secondary' bit (which equals 256) set in its FLAGS field.
1215 For reads that have more than <int> distinct, valid alignments, bowtie2
1216 does not guarantee that the <int> alignments reported are the best
1217 possible in terms of alignment score. -k is mutually exclusive with -a.
1218
1219 Note: Bowtie 2 is not designed with large values for -k in mind, and
1220 when aligning reads to long, repetitive genomes large -k can be very,
1221 very slow.
1222
1223 -a
1224
1225 Like -k but with no upper limit on number of alignments to search for.
1226 -a is mutually exclusive with -k.
1227
1228 Note: Bowtie 2 is not designed with -a mode in mind, and when aligning
1229 reads to long, repetitive genomes this mode can be very, very slow.
1230
1231 Effort options
1232
1233 -D <int>
1234
1235 Up to <int> consecutive seed extension attempts can "fail" before Bowtie
1236 2 moves on, using the alignments found so far. A seed extension "fails"
1237 if it does not yield a new best or a new second-best alignment. This
1238 limit is automatically adjusted up when -k or -a are specified. Default:
1239 15.
1240
1241 -R <int>
1242
1243 <int> is the maximum number of times Bowtie 2 will "re-seed" reads with
1244 repetitive seeds. When "re-seeding," Bowtie 2 simply chooses a new set
1245 of reads (same length, same number of mismatches allowed) at different
1246 offsets and searches for more alignments. A read is considered to have
1247 repetitive seeds if the total number of seed hits divided by the number
1248 of seeds that aligned at least once is greater than 300. Default: 2.
1249
1250 -d/--deterministic-seeds
1251
1252 Consider all seeds in order (no subsampling). Can be used to augment -a
1253 or -k with deterministic behavior. This option significantly speeds up
1254 -a while also reducing memory consumption. It is not however always
1255 strictly better than standalone [-a] when considering the number of
1256 repeated alignments found.
1257
1258 Note: In order to use this option exact upfront and 1mm upfront behavior
1259 have to be disabled using the following options: [--no-exact-upfront]
1260 and --no-1mm-upfront.
1261
1262 Paired-end options
1263
1264 -I/--minins <int>
1265
1266 The minimum fragment length for valid paired-end alignments. E.g. if
1267 -I 60 is specified and a paired-end alignment consists of two 20-bp
1268 alignments in the appropriate orientation with a 20-bp gap between them,
1269 that alignment is considered valid (as long as -X is also satisfied). A
1270 19-bp gap would not be valid in that case. If trimming options -3 or -5
1271 are also used, the -I constraint is applied with respect to the
1272 untrimmed mates.
1273
1274 The larger the difference between -I and -X, the slower Bowtie 2 will
1275 run. This is because larger differences between -I and -X require that
1276 Bowtie 2 scan a larger window to determine if a concordant alignment
1277 exists. For typical fragment length ranges (200 to 400 nucleotides),
1278 Bowtie 2 is very efficient.
1279
1280 Default: 0 (essentially imposing no minimum)
1281
1282 -X/--maxins <int>
1283
1284 The maximum fragment length for valid paired-end alignments. E.g. if
1285 -X 100 is specified and a paired-end alignment consists of two 20-bp
1286 alignments in the proper orientation with a 60-bp gap between them, that
1287 alignment is considered valid (as long as -I is also satisfied). A 61-bp
1288 gap would not be valid in that case. If trimming options -3 or -5 are
1289 also used, the -X constraint is applied with respect to the untrimmed
1290 mates, not the trimmed mates.
1291
1292 The larger the difference between -I and -X, the slower Bowtie 2 will
1293 run. This is because larger differences between -I and -X require that
1294 Bowtie 2 scan a larger window to determine if a concordant alignment
1295 exists. For typical fragment length ranges (200 to 400 nucleotides),
1296 Bowtie 2 is very efficient.
1297
1298 Default: 500.
1299
1300 --fr/--rf/--ff
1301
1302 The upstream/downstream mate orientations for a valid paired-end
1303 alignment against the forward reference strand. E.g., if --fr is
1304 specified and there is a candidate paired-end alignment where mate 1
1305 appears upstream of the reverse complement of mate 2 and the fragment
1306 length constraints (-I and -X) are met, that alignment is valid. Also,
1307 if mate 2 appears upstream of the reverse complement of mate 1 and all
1308 other constraints are met, that too is valid. --rf likewise requires
1309 that an upstream mate1 be reverse-complemented and a downstream mate2 be
1310 forward-oriented. --ff requires both an upstream mate 1 and a downstream
1311 mate 2 to be forward-oriented. Default: --fr (appropriate for Illumina's
1312 Paired-end Sequencing Assay).
1313
1314 --no-mixed
1315
1316 By default, when bowtie2 cannot find a concordant or discordant
1317 alignment for a pair, it then tries to find alignments for the
1318 individual mates. This option disables that behavior.
1319
1320 --no-discordant
1321
1322 By default, bowtie2 looks for discordant alignments if it cannot find
1323 any concordant alignments. A discordant alignment is an alignment where
1324 both mates align uniquely, but that does not satisfy the paired-end
1325 constraints (--fr/--rf/--ff, -I, -X). This option disables that
1326 behavior.
1327
1328 --dovetail
1329
1330 If the mates "dovetail", that is if one mate alignment extends past the
1331 beginning of the other such that the wrong mate begins upstream,
1332 consider that to be concordant. See also: Mates can overlap, contain or
1333 dovetail each other. Default: mates cannot dovetail in a concordant
1334 alignment.
1335
1336 --no-contain
1337
1338 If one mate alignment contains the other, consider that to be
1339 non-concordant. See also: Mates can overlap, contain or dovetail each
1340 other. Default: a mate can contain the other in a concordant alignment.
1341
1342 --no-overlap
1343
1344 If one mate alignment overlaps the other at all, consider that to be
1345 non-concordant. See also: Mates can overlap, contain or dovetail each
1346 other. Default: mates can overlap in a concordant alignment.
1347
1348 BAM options
1349
1350 --align-paired-reads
1351
1352 Bowtie 2 will, by default, attempt to align unpaired BAM reads. Use this
1353 option to align paired-end reads instead.
1354
1355 --preserve-tags
1356
1357 Preserve tags from the original BAM record by appending them to the end
1358 of the corresponding Bowtie 2 SAM output.
1359
1360 Output options
1361
1362 -t/--time
1363
1364 Print the wall-clock time required to load the index files and align the
1365 reads. This is printed to the "standard error" ("stderr") filehandle.
1366 Default: off.
1367
1368 --un <path>
1369 --un-gz <path>
1370 --un-bz2 <path>
1371 --un-lz4 <path>
1372
1373 Write unpaired reads that fail to align to file at <path>. These reads
1374 correspond to the SAM records with the FLAGS 0x4 bit set and neither the
1375 0x40 nor 0x80 bits set. If --un-gz is specified, output will be gzip
1376 compressed. If --un-bz2 or --un-lz4 is specified, output will be bzip2
1377 or lz4 compressed. Reads written in this way will appear exactly as they
1378 did in the input file, without any modification (same sequence, same
1379 name, same quality string, same quality encoding). Reads will not
1380 necessarily appear in the same order as they did in the input.
1381
1382 --al <path>
1383 --al-gz <path>
1384 --al-bz2 <path>
1385 --al-lz4 <path>
1386
1387 Write unpaired reads that align at least once to file at <path>. These
1388 reads correspond to the SAM records with the FLAGS 0x4, 0x40, and 0x80
1389 bits unset. If --al-gz is specified, output will be gzip compressed. If
1390 --al-bz2 is specified, output will be bzip2 compressed. Similarly if
1391 --al-lz4 is specified, output will be lz4 compressed. Reads written in
1392 this way will appear exactly as they did in the input file, without any
1393 modification (same sequence, same name, same quality string, same
1394 quality encoding). Reads will not necessarily appear in the same order
1395 as they did in the input.
1396
1397 --un-conc <path>
1398 --un-conc-gz <path>
1399 --un-conc-bz2 <path>
1400 --un-conc-lz4 <path>
1401
1402 Write paired-end reads that fail to align concordantly to file(s) at
1403 <path>. These reads correspond to the SAM records with the FLAGS 0x4 bit
1404 set and either the 0x40 or 0x80 bit set (depending on whether it's mate
1405 #1 or #2). .1 and .2 strings are added to the filename to distinguish
1406 which file contains mate #1 and mate #2. If a percent symbol, %, is used
1407 in <path>, the percent symbol is replaced with 1 or 2 to make the
1408 per-mate filenames. Otherwise, .1 or .2 are added before the final dot
1409 in <path> to make the per-mate filenames. Reads written in this way will
1410 appear exactly as they did in the input files, without any modification
1411 (same sequence, same name, same quality string, same quality encoding).
1412 Reads will not necessarily appear in the same order as they did in the
1413 inputs.
1414
1415 --al-conc <path>
1416 --al-conc-gz <path>
1417 --al-conc-bz2 <path>
1418 --al-conc-lz4 <path>
1419
1420 Write paired-end reads that align concordantly at least once to file(s)
1421 at <path>. These reads correspond to the SAM records with the FLAGS 0x4
1422 bit unset and either the 0x40 or 0x80 bit set (depending on whether it's
1423 mate #1 or #2). .1 and .2 strings are added to the filename to
1424 distinguish which file contains mate #1 and mate #2. If a percent
1425 symbol, %, is used in <path>, the percent symbol is replaced with 1 or 2
1426 to make the per-mate filenames. Otherwise, .1 or .2 are added before the
1427 final dot in <path> to make the per-mate filenames. Reads written in
1428 this way will appear exactly as they did in the input files, without any
1429 modification (same sequence, same name, same quality string, same
1430 quality encoding). Reads will not necessarily appear in the same order
1431 as they did in the inputs.
1432
1433 --quiet
1434
1435 Print nothing besides alignments and serious errors.
1436
1437 --met-file <path>
1438
1439 Write bowtie2 metrics to file <path>. Having alignment metric can be
1440 useful for debugging certain problems, especially performance issues.
1441 See also: --met. Default: metrics disabled.
1442
1443 --met-stderr <path>
1444
1445 Write bowtie2 metrics to the "standard error" ("stderr") filehandle.
1446 This is not mutually exclusive with --met-file. Having alignment metric
1447 can be useful for debugging certain problems, especially performance
1448 issues. See also: --met. Default: metrics disabled.
1449
1450 --met <int>
1451
1452 Write a new bowtie2 metrics record every <int> seconds. Only matters if
1453 either --met-stderr or --met-file are specified. Default: 1.
1454
1455 SAM options
1456
1457 --no-unal
1458
1459 Suppress SAM records for reads that failed to align.
1460
1461 --no-hd
1462
1463 Suppress SAM header lines (starting with @).
1464
1465 --no-sq
1466
1467 Suppress @SQ SAM header lines.
1468
1469 --rg-id <text>
1470
1471 Set the read group ID to <text>. This causes the SAM @RG header line to
1472 be printed, with <text> as the value associated with the ID: tag. It
1473 also causes the RG:Z: extra field to be attached to each SAM output
1474 record, with value set to <text>.
1475
1476 --rg <text>
1477
1478 Add <text> (usually of the form TAG:VAL, e.g. SM:Pool1) as a field on
1479 the @RG header line. Note: in order for the @RG line to appear, --rg-id
1480 must also be specified. This is because the ID tag is required by the
1481 SAM Spec. Specify --rg multiple times to set multiple fields. See the
1482 SAM Spec for details about what fields are legal.
1483
1484 --omit-sec-seq
1485
1486 When printing secondary alignments, Bowtie 2 by default will write out
1487 the SEQ and QUAL strings. Specifying this option causes Bowtie 2 to
1488 print an asterisk in those fields instead.
1489
1490 --soft-clipped-unmapped-tlen
1491
1492 Consider soft-clipped bases unmapped when calculating TLEN. Only
1493 available in --local mode.
1494
1495 --sam-no-qname-trunc
1496
1497 Suppress standard behavior of truncating readname at first whitespace at
1498 the expense of generating non-standard SAM
1499
1500 --xeq
1501
1502 Use '='/'X', instead of 'M', to specify matches/mismatches in SAM record
1503
1504 --sam-append-comment
1505
1506 Append FASTA/FASTQ comment to SAM record, where a comment is everything
1507 after the first space in the read name.
1508
1509 --sam-opt-config <config>
1510
1511 Use <config> to toggle SAM Optional Fields where <config> is a string of
1512 comma delimited, case-insensitive, two-letter tags. Tags prefixed with a
1513 "-" will be turned off and hence will not be included in the SAM output.
1514 The example below turns off the "MD" tag and enables the
1515 bowtie2-specific "YP" tag. The config is additive, so, any default OPT
1516 flags that need to be turned off will have to explicitly specified.
1517
1518 `bowtie2 ... --sam-opt-config "-md,yp"
1519
1520 Performance options
1521
1522 -o/--offrate <int>
1523
1524 Override the offrate of the index with <int>. If <int> is greater than
1525 the offrate used to build the index, then some row markings are
1526 discarded when the index is read into memory. This reduces the memory
1527 footprint of the aligner but requires more time to calculate text
1528 offsets. <int> must be greater than the value used to build the index.
1529
1530 -p/--threads NTHREADS
1531
1532 Launch NTHREADS parallel search threads (default: 1). Threads will run
1533 on separate processors/cores and synchronize when parsing reads and
1534 outputting alignments. Searching for alignments is highly parallel, and
1535 speedup is close to linear. Increasing -p increases Bowtie 2's memory
1536 footprint. E.g. when aligning to a human genome index, increasing -p
1537 from 1 to 8 increases the memory footprint by a few hundred megabytes.
1538 This option is only available if bowtie is linked with the pthreads
1539 library (i.e. if BOWTIE_PTHREADS=0 is not specified at build time).
1540
1541 --reorder
1542
1543 Guarantees that output SAM records are printed in an order corresponding
1544 to the order of the reads in the original input file, even when -p is
1545 set greater than 1. Specifying --reorder and setting -p greater than 1
1546 causes Bowtie 2 to run somewhat slower and use somewhat more memory than
1547 if --reorder were not specified. Has no effect if -p is set to 1, since
1548 output order will naturally correspond to input order in that case.
1549
1550 --mm
1551
1552 Use memory-mapped I/O to load the index, rather than typical file I/O.
1553 Memory-mapping allows many concurrent bowtie processes on the same
1554 computer to share the same memory image of the index (i.e. you pay the
1555 memory overhead just once). This facilitates memory-efficient
1556 parallelization of bowtie in situations where using -p is not possible
1557 or not preferable.
1558
1559 Other options
1560
1561 --qc-filter
1562
1563 Filter out reads for which the QSEQ filter field is non-zero. Only has
1564 an effect when read format is --qseq. Default: off.
1565
1566 --seed <int>
1567
1568 Use <int> as the seed for pseudo-random number generator. Default: 0.
1569
1570 --non-deterministic
1571
1572 Normally, Bowtie 2 re-initializes its pseudo-random generator for each
1573 read. It seeds the generator with a number derived from (a) the read
1574 name, (b) the nucleotide sequence, (c) the quality sequence, (d) the
1575 value of the --seed option. This means that if two reads are identical
1576 (same name, same nucleotides, same qualities) Bowtie 2 will find and
1577 report the same alignment(s) for both, even if there was ambiguity. When
1578 --non-deterministic is specified, Bowtie 2 re-initializes its
1579 pseudo-random generator for each read using the current time. This means
1580 that Bowtie 2 will not necessarily report the same alignment for two
1581 identical reads. This is counter-intuitive for some users, but might be
1582 more appropriate in situations where the input consists of many
1583 identical reads.
1584
1585 --version
1586
1587 Print version information and quit.
1588
1589 -h/--help
1590
1591 Print usage information and quit.
1592
1593 SAM output
1594
1595 Following is a brief description of the SAM format as output by bowtie2.
1596 For more details, see the SAM format specification.
1597
1598 By default, bowtie2 prints a SAM header with @HD, @SQ and @PG lines.
1599 When one or more --rg arguments are specified, bowtie2 will also print
1600 an @RG line that includes all user-specified --rg tokens separated by
1601 tabs.
1602
1603 Each subsequent line describes an alignment or, if the read failed to
1604 align, a read. Each line is a collection of at least 12 fields separated
1605 by tabs; from left to right, the fields are:
1606
1607 1. Name of read that aligned.
1608
1609 Note that the SAM specification disallows whitespace in the read
1610 name. If the read name contains any whitespace characters, Bowtie 2
1611 will truncate the name at the first whitespace character. This is
1612 similar to the behavior of other tools. The standard behavior of
1613 truncating at the first whitespace can be suppressed with
1614 --sam-no-qname-trunc at the expense of generating non-standard SAM.
1615
1616 2. Sum of all applicable flags. Flags relevant to Bowtie are:
1617
1618 1
1619
1620 The read is one of a pair
1621
1622 2
1623
1624 The alignment is one end of a proper paired-end alignment
1625
1626 4
1627
1628 The read has no reported alignments
1629
1630 8
1631
1632 The read is one of a pair and has no reported alignments
1633
1634 16
1635
1636 The alignment is to the reverse reference strand
1637
1638 32
1639
1640 The other mate in the paired-end alignment is aligned to the reverse
1641 reference strand
1642
1643 64
1644
1645 The read is mate 1 in a pair
1646
1647 128
1648
1649 The read is mate 2 in a pair
1650
1651 Thus, an unpaired read that aligns to the reverse reference strand
1652 will have flag 16. A paired-end read that aligns and is the first
1653 mate in the pair will have flag 83 (= 64 + 16 + 2 + 1).
1654
1655 3. Name of reference sequence where alignment occurs
1656
1657 4. 1-based offset into the forward reference strand where leftmost
1658 character of the alignment occurs
1659
1660 5. Mapping quality
1661
1662 6. CIGAR string representation of alignment
1663
1664 7. Name of reference sequence where mate's alignment occurs. Set to =
1665 if the mate's reference sequence is the same as this alignment's,
1666 or * if there is no mate.
1667
1668 8. 1-based offset into the forward reference strand where leftmost
1669 character of the mate's alignment occurs. Offset is 0 if there is no
1670 mate.
1671
1672 9. Inferred fragment length. Size is negative if the mate's alignment
1673 occurs upstream of this alignment. Size is 0 if the mates did not
1674 align concordantly. However, size is non-0 if the mates aligned
1675 discordantly to the same chromosome.
1676
1677 10. Read sequence (reverse-complemented if aligned to the reverse
1678 strand)
1679
1680 11. ASCII-encoded read qualities (reverse-complemented if the read
1681 aligned to the reverse strand). The encoded quality values are on
1682 the Phred quality scale and the encoding is ASCII-offset by 33
1683 (ASCII char !), similarly to a FASTQ file.
1684
1685 12. Optional fields. Fields are tab-separated. bowtie2 outputs zero or
1686 more of these optional fields for each alignment, depending on the
1687 type of the alignment:
1688
1689 AS:i:<N>
1690
1691 Alignment score. Can be negative. Can be greater than 0 in --local mode
1692 (but not in --end-to-end mode). Only present if SAM record is for an
1693 aligned read.
1694
1695 XS:i:<N>
1696
1697 Alignment score for the best-scoring alignment found other than the
1698 alignment reported. Can be negative. Can be greater than 0 in --local
1699 mode (but not in --end-to-end mode). Only present if the SAM record is
1700 for an aligned read and more than one alignment was found for the read.
1701 Note that, when the read is part of a concordantly-aligned pair, this
1702 score could be greater than AS:i.
1703
1704 YS:i:<N>
1705
1706 Alignment score for opposite mate in the paired-end alignment. Only
1707 present if the SAM record is for a read that aligned as part of a
1708 paired-end alignment.
1709
1710 XN:i:<N>
1711
1712 The number of ambiguous bases in the reference covering this alignment.
1713 Only present if SAM record is for an aligned read.
1714
1715 XM:i:<N>
1716
1717 The number of mismatches in the alignment. Only present if SAM record is
1718 for an aligned read.
1719
1720 XO:i:<N>
1721
1722 The number of gap opens, for both read and reference gaps, in the
1723 alignment. Only present if SAM record is for an aligned read.
1724
1725 XG:i:<N>
1726
1727 The number of gap extensions, for both read and reference gaps, in the
1728 alignment. Only present if SAM record is for an aligned read.
1729
1730 NM:i:<N>
1731
1732 The edit distance; that is, the minimal number of one-nucleotide edits
1733 (substitutions, insertions and deletions) needed to transform the read
1734 string into the reference string. Only present if SAM record is for an
1735 aligned read.
1736
1737 YF:Z:<S>
1738
1739 String indicating reason why the read was filtered out. See also:
1740 Filtering. Only appears for reads that were filtered out.
1741
1742 YT:Z:<S>
1743
1744 Value of UU indicates the read was not part of a pair. Value of CP
1745 indicates the read was part of a pair and the pair aligned concordantly.
1746 Value of DP indicates the read was part of a pair and the pair aligned
1747 discordantly. Value of UP indicates the read was part of a pair but the
1748 pair failed to aligned either concordantly or discordantly.
1749
1750 MD:Z:<S>
1751
1752 A string representation of the mismatched reference bases in the
1753 alignment. See SAM Tags format specification for details. Only present
1754 if SAM record is for an aligned read.
1755
1756 The bowtie2-build indexer
1757
1758 bowtie2-build builds a Bowtie index from a set of DNA sequences.
1759 bowtie2-build outputs a set of 6 files with suffixes .1.bt2, .2.bt2,
1760 .3.bt2, .4.bt2, .rev.1.bt2, and .rev.2.bt2. In the case of a large index
1761 these suffixes will have a bt2l termination. These files together
1762 constitute the index: they are all that is needed to align reads to that
1763 reference. The original sequence FASTA files are no longer used by
1764 Bowtie 2 once the index is built.
1765
1766 Bowtie 2's .bt2 index format is different from Bowtie 1's .ebwt format,
1767 and they are not compatible with each other.
1768
1769 Use of Karkkainen's blockwise algorithm allows bowtie2-build to trade
1770 off between running time and memory usage. bowtie2-build has three
1771 options governing how it makes this trade: -p/--packed,
1772 --bmax/--bmaxdivn, and --dcv. By default, bowtie2-build will
1773 automatically search for the settings that yield the best running time
1774 without exhausting memory. This behavior can be disabled using the
1775 -a/--noauto option.
1776
1777 The indexer provides options pertaining to the "shape" of the index,
1778 e.g. --offrate governs the fraction of Burrows-Wheeler rows that are
1779 "marked" (i.e., the density of the suffix-array sample; see the original
1780 FM Index paper for details). All of these options are potentially
1781 profitable trade-offs depending on the application. They have been set
1782 to defaults that are reasonable for most cases according to our
1783 experiments. See Performance tuning for details.
1784
1785 bowtie2-build can generate either small or large indexes. The wrapper
1786 will decide which based on the length of the input genome. If the
1787 reference does not exceed 4 billion characters but a large index is
1788 preferred, the user can specify --large-index to force bowtie2-build to
1789 build a large index instead.
1790
1791 The Bowtie 2 index is based on the FM Index of Ferragina and Manzini,
1792 which in turn is based on the Burrows-Wheeler transform. The algorithm
1793 used to build the index is based on the blockwise algorithm of
1794 Karkkainen.
1795
1796 Command Line
1797
1798 Usage:
1799
1800 bowtie2-build [options]* <reference_in> <bt2_base>
1801
1802 Main arguments
1803
1804 <reference_in>
1805
1806 A comma-separated list of FASTA files containing the reference sequences
1807 to be aligned to, or, if -c is specified, the sequences themselves.
1808 E.g., <reference_in> might be chr1.fa,chr2.fa,chrX.fa,chrY.fa, or, if -c
1809 is specified, this might be GGTCATCCT,ACGGGTCGT,CCGTTCTATGCGGCTTA.
1810
1811 <bt2_base>
1812
1813 The basename of the index files to write. By default, bowtie2-build
1814 writes files named NAME.1.bt2, NAME.2.bt2, NAME.3.bt2, NAME.4.bt2,
1815 NAME.rev.1.bt2, and NAME.rev.2.bt2, where NAME is <bt2_base>.
1816
1817 Options
1818
1819 -f
1820
1821 The reference input files (specified as <reference_in>) are FASTA files
1822 (usually having extension .fa, .mfa, .fna or similar).
1823
1824 -c
1825
1826 The reference sequences are given on the command line. I.e.
1827 <reference_in> is a comma-separated list of sequences rather than a list
1828 of FASTA files.
1829
1830 --large-index
1831
1832 Force bowtie2-build to build a large index, even if the reference is
1833 less than ~ 4 billion nucleotides inlong.
1834
1835 -a/--noauto
1836
1837 Disable the default behavior whereby bowtie2-build automatically selects
1838 values for the --bmax, --dcv and --packed parameters according to
1839 available memory. Instead, user may specify values for those parameters.
1840 If memory is exhausted during indexing, an error message will be
1841 printed; it is up to the user to try new parameters.
1842
1843 -p/--packed
1844
1845 Use a packed (2-bits-per-nucleotide) representation for DNA strings.
1846 This saves memory but makes indexing 2-3 times slower. Default: off.
1847 This is configured automatically by default; use -a/--noauto to
1848 configure manually.
1849
1850 --bmax <int>
1851
1852 The maximum number of suffixes allowed in a block. Allowing more
1853 suffixes per block makes indexing faster, but increases peak memory
1854 usage. Setting this option overrides any previous setting for --bmax, or
1855 --bmaxdivn. Default (in terms of the --bmaxdivn parameter) is --bmaxdivn
1856 4 * number of threads. This is configured automatically by default; use
1857 -a/--noauto to configure manually.
1858
1859 --bmaxdivn <int>
1860
1861 The maximum number of suffixes allowed in a block, expressed as a
1862 fraction of the length of the reference. Setting this option overrides
1863 any previous setting for --bmax, or --bmaxdivn. Default: --bmaxdivn 4 *
1864 number of threads. This is configured automatically by default; use
1865 -a/--noauto to configure manually.
1866
1867 --dcv <int>
1868
1869 Use <int> as the period for the difference-cover sample. A larger period
1870 yields less memory overhead, but may make suffix sorting slower,
1871 especially if repeats are present. Must be a power of 2 no greater than
1872 4096. Default: 1024. This is configured automatically by default; use
1873 -a/--noauto to configure manually.
1874
1875 --nodc
1876
1877 Disable use of the difference-cover sample. Suffix sorting becomes
1878 quadratic-time in the worst case (where the worst case is an extremely
1879 repetitive reference). Default: off.
1880
1881 -r/--noref
1882
1883 Do not build the NAME.3.bt2 and NAME.4.bt2 portions of the index, which
1884 contain a bitpacked version of the reference sequences and are used for
1885 paired-end alignment.
1886
1887 -3/--justref
1888
1889 Build only the NAME.3.bt2 and NAME.4.bt2 portions of the index, which
1890 contain a bitpacked version of the reference sequences and are used for
1891 paired-end alignment.
1892
1893 -o/--offrate <int>
1894
1895 To map alignments back to positions on the reference sequences, it's
1896 necessary to annotate ("mark") some or all of the Burrows-Wheeler rows
1897 with their corresponding location on the genome. -o/--offrate governs
1898 how many rows get marked: the indexer will mark every 2^<int> rows.
1899 Marking more rows makes reference-position lookups faster, but requires
1900 more memory to hold the annotations at runtime. The default is 5 (every
1901 32nd row is marked; for human genome, annotations occupy about 340
1902 megabytes).
1903
1904 -t/--ftabchars <int>
1905
1906 The ftab is the lookup table used to calculate an initial
1907 Burrows-Wheeler range with respect to the first <int> characters of the
1908 query. A larger <int> yields a larger lookup table but faster query
1909 times. The ftab has size 4^(<int>+1) bytes. The default setting is 10
1910 (ftab is 4MB).
1911
1912 --seed <int>
1913
1914 Use <int> as the seed for pseudo-random number generator.
1915
1916 --cutoff <int>
1917
1918 Index only the first <int> bases of the reference sequences (cumulative
1919 across sequences) and ignore the rest.
1920
1921 -q/--quiet
1922
1923 bowtie2-build is verbose by default. With this option bowtie2-build will
1924 print only error messages.
1925
1926 --threads <int>
1927
1928 By default bowtie2-build is using only one thread. Increasing the number
1929 of threads will speed up the index building considerably in most cases.
1930
1931 -h/--help
1932
1933 Print usage information and quit.
1934
1935 --version
1936
1937 Print version information and quit.
1938
1939 The bowtie2-inspect index inspector
1940
1941 bowtie2-inspect extracts information from a Bowtie index about what kind
1942 of index it is and what reference sequences were used to build it. When
1943 run without any options, the tool will output a FASTA file containing
1944 the sequences of the original references (with all non-A/C/G/T
1945 characters converted to Ns). It can also be used to extract just the
1946 reference sequence names using the -n/--names option or a more verbose
1947 summary using the -s/--summary option.
1948
1949 Command Line
1950
1951 Usage:
1952
1953 bowtie2-inspect [options]* <bt2_base>
1954
1955 Main arguments
1956
1957 <bt2_base>
1958
1959 The basename of the index to be inspected. The basename is name of any
1960 of the index files but with the .X.bt2 or .rev.X.bt2 suffix omitted.
1961 bowtie2-inspect first looks in the current directory for the index
1962 files, then in the directory specified in the BOWTIE2_INDEXES
1963 environment variable.
1964
1965 Options
1966
1967 -a/--across <int>
1968
1969 When printing FASTA output, output a newline character every <int> bases
1970 (default: 60).
1971
1972 -n/--names
1973
1974 Print reference sequence names, one per line, and quit.
1975
1976 -s/--summary
1977
1978 Print a summary that includes information about index settings, as well
1979 as the names and lengths of the input sequences. The summary has this
1980 format:
1981
1982 Colorspace <0 or 1>
1983 SA-Sample 1 in <sample>
1984 FTab-Chars <chars>
1985 Sequence-1 <name> <len>
1986 Sequence-2 <name> <len>
1987 ...
1988 Sequence-N <name> <len>
1989
1990 Fields are separated by tabs. Colorspace is always set to 0 for Bowtie
1991 2.
1992
1993 -o/--output <filename>
1994
1995 Save output to user-specified filename (default: stdout)
1996
1997 -v/--verbose
1998
1999 Print verbose output (for debugging).
2000
2001 --version
2002
2003 Print version information and quit.
2004
2005 -h/--help
2006
2007 Print usage information and quit.
2008
2009 Getting started with Bowtie 2: Lambda phage example
2010
2011 Bowtie 2 comes with some example files to get you started. The example
2012 files are not scientifically significant; we use the Lambda phage
2013 reference genome simply because it's short, and the reads were generated
2014 by a computer program, not a sequencer. However, these files will let
2015 you start running Bowtie 2 and downstream tools right away.
2016
2017 First follow the manual instructions to obtain Bowtie 2. Set the
2018 BT2_HOME environment variable to point to the new Bowtie 2 directory
2019 containing the bowtie2, bowtie2-build and bowtie2-inspect binaries. This
2020 is important, as the BT2_HOME variable is used in the commands below to
2021 refer to that directory.
2022
2023 Indexing a reference genome
2024
2025 To create an index for the Lambda phage reference genome included with
2026 Bowtie 2, create a new temporary directory (it doesn't matter where),
2027 change into that directory, and run:
2028
2029 $BT2_HOME/bowtie2-build $BT2_HOME/example/reference/lambda_virus.fa lambda_virus
2030
2031 The command should print many lines of output then quit. When the
2032 command completes, the current directory will contain four new files
2033 that all start with lambda_virus and end with .1.bt2, .2.bt2, .3.bt2,
2034 .4.bt2, .rev.1.bt2, and .rev.2.bt2. These files constitute the index -
2035 you're done!
2036
2037 You can use bowtie2-build to create an index for a set of FASTA files
2038 obtained from any source, including sites such as UCSC, NCBI, and
2039 Ensembl. When indexing multiple FASTA files, specify all the files using
2040 commas to separate file names. For more details on how to create an
2041 index with bowtie2-build, see the manual section on index building. You
2042 may also want to bypass this process by obtaining a pre-built index. See
2043 using a pre-built index below for an example.
2044
2045 Aligning example reads
2046
2047 Stay in the directory created in the previous step, which now contains
2048 the lambda_virus index files. Next, run:
2049
2050 $BT2_HOME/bowtie2 -x lambda_virus -U $BT2_HOME/example/reads/reads_1.fq -S eg1.sam
2051
2052 This runs the Bowtie 2 aligner, which aligns a set of unpaired reads to
2053 the Lambda phage reference genome using the index generated in the
2054 previous step. The alignment results in SAM format are written to the
2055 file eg1.sam, and a short alignment summary is written to the console.
2056 (Actually, the summary is written to the "standard error" or "stderr"
2057 filehandle, which is typically printed to the console.)
2058
2059 To see the first few lines of the SAM output, run:
2060
2061 head eg1.sam
2062
2063 You will see something like this:
2064
2065 @HD VN:1.0 SO:unsorted
2066 @SQ SN:gi|9626243|ref|NC_001416.1| LN:48502
2067 @PG ID:bowtie2 PN:bowtie2 VN:2.0.1
2068 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
2069 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
2070 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
2071 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
2072 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
2073 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
2074 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
2075
2076 The first few lines (beginning with @) are SAM header lines, and the
2077 rest of the lines are SAM alignments, one line per read or mate. See the
2078 Bowtie 2 manual section on SAM output and the SAM specification for
2079 details about how to interpret the SAM file format.
2080
2081 Paired-end example
2082
2083 To align paired-end reads included with Bowtie 2, stay in the same
2084 directory and run:
2085
2086 $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
2087
2088 This aligns a set of paired-end reads to the reference genome, with
2089 results written to the file eg2.sam.
2090
2091 Local alignment example
2092
2093 To use local alignment to align some longer reads included with Bowtie
2094 2, stay in the same directory and run:
2095
2096 $BT2_HOME/bowtie2 --local -x lambda_virus -U $BT2_HOME/example/reads/longreads.fq -S eg3.sam
2097
2098 This aligns the long reads to the reference genome using local
2099 alignment, with results written to the file eg3.sam.
2100
2101 Using SAMtools/BCFtools downstream
2102
2103 SAMtools is a collection of tools for manipulating and analyzing SAM and
2104 BAM alignment files. BCFtools is a collection of tools for calling
2105 variants and manipulating VCF and BCF files, and it is typically
2106 distributed with SAMtools. Using these tools together allows you to get
2107 from alignments in SAM format to variant calls in VCF format. This
2108 example assumes that samtools and bcftools are installed and that the
2109 directories containing these binaries are in your PATH environment
2110 variable.
2111
2112 Run the paired-end example:
2113
2114 $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
2115
2116 Use samtools view to convert the SAM file into a BAM file. BAM is the
2117 binary format corresponding to the SAM text format. Run:
2118
2119 samtools view -bS eg2.sam > eg2.bam
2120
2121 Use samtools sort to convert the BAM file to a sorted BAM file.
2122
2123 samtools sort eg2.bam -o eg2.sorted.bam
2124
2125 We now have a sorted BAM file called eg2.sorted.bam. Sorted BAM is a
2126 useful format because the alignments are (a) compressed, which is
2127 convenient for long-term storage, and (b) sorted, which is conveneint
2128 for variant discovery. To generate variant calls in VCF format, run:
2129
2130 bcftools mpileup -f $BT2_HOME/example/reference/lambda_virus.fa eg2.sorted.bam | bcftools view -Ov - > eg2.raw.bcf
2131
2132 Then to view the variants, run:
2133
2134 bcftools view eg2.raw.bcf
2135
2136 See the official SAMtools guide to Calling SNPs/INDELs with
2137 SAMtools/BCFtools for more details and variations on this process.