Debian Codegraph @

doc/manual.html

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