| 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 && 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 && 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 && 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 && 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 >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 >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 >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 <bt2-idx> {-1 <m1> -2 <m2> | -U <r> | --interleaved <i> | --sra-acc <acc> | -b <bam>} -S [<sam>]</code></pre> |
| 1044 |
<h3 id="main-arguments">Main arguments</h3> |
| 1045 |
<table> |
| 1046 |
<tr> |
| 1047 |
<td id="bowtie2-options-x"> |
| 1048 |
<pre><code>-x <bt2-idx></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 <m1></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><m2></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 <m2></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><m1></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 <r></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 <bam></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 <sam></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><m1></code>, |
| 1154 |
<code><m2></code>, <code><s></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><m1></code>, |
| 1190 |
<code><m2></code>, <code><s></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><m1></code>, |
| 1202 |
<code><m2></code>, <code><s></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><m1></code>, |
| 1220 |
<code><m2></code>, <code><s></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:<int>,i:<int></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><sequence>_<offset></code>, where |
| 1238 |
<code><sequence></code> is the name of the FASTA sequence it was |
| 1239 |
drawn from and <code><offset></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><m1></code>, <code><m2></code> and |
| 1251 |
<code><singles></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 <int></code></pre> |
| 1260 |
</td> |
| 1261 |
<td> |
| 1262 |
<p>Skip (i.e. do not align) the first <code><int></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 <int></code></pre> |
| 1269 |
</td> |
| 1270 |
<td> |
| 1271 |
<p>Align the first <code><int></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 <int></code></pre> |
| 1280 |
</td> |
| 1281 |
<td> |
| 1282 |
<p>Trim <code><int></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 <int></code></pre> |
| 1289 |
</td> |
| 1290 |
<td> |
| 1291 |
<p>Trim <code><int></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:]<int></code></pre> |
| 1298 |
</td> |
| 1299 |
<td> |
| 1300 |
<p>Trim reads exceeding <code><int></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 <int></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 <int></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 <func></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 <func></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 <int></code></pre> |
| 1514 |
</td> |
| 1515 |
<td> |
| 1516 |
<p>"Pads" dynamic programming problems by <code><int></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 <int></code></pre> |
| 1523 |
</td> |
| 1524 |
<td> |
| 1525 |
<p>Disallow gaps within <code><int></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 <int></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><int></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 <int></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 <int1>,<int2></code></pre> |
| 1668 |
</td> |
| 1669 |
<td> |
| 1670 |
<p>Sets the read gap open (<code><int1></code>) and extend |
| 1671 |
(<code><int2></code>) penalties. A read gap of length N gets a |
| 1672 |
penalty of <code><int1></code> + N * <code><int2></code>. |
| 1673 |
Default: 5, 3.</p> |
| 1674 |
</td> |
| 1675 |
</tr> |
| 1676 |
<tr> |
| 1677 |
<td id="bowtie2-options-rfg"> |
| 1678 |
<pre><code>--rfg <int1>,<int2></code></pre> |
| 1679 |
</td> |
| 1680 |
<td> |
| 1681 |
<p>Sets the reference gap open (<code><int1></code>) and extend |
| 1682 |
(<code><int2></code>) penalties. A reference gap of length N gets |
| 1683 |
a penalty of <code><int1></code> + N * <code><int2></code>. |
| 1684 |
Default: 5, 3.</p> |
| 1685 |
</td> |
| 1686 |
</tr> |
| 1687 |
<tr> |
| 1688 |
<td id="bowtie2-options-score-min"> |
| 1689 |
<pre><code>--score-min <func></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 <int></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><int></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><int></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><int></code> distinct, valid alignments, |
| 1732 |
<code>bowtie2</code> does not guarantee that the |
| 1733 |
<code><int></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 <int></code></pre> |
| 1761 |
</td> |
| 1762 |
<td> |
| 1763 |
<p>Up to <code><int></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 <int></code></pre> |
| 1773 |
</td> |
| 1774 |
<td> |
| 1775 |
<p><code><int></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 <int></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 <int></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 <path> |
| 1980 |
--un-gz <path> |
| 1981 |
--un-bz2 <path> |
| 1982 |
--un-lz4 <path></code></pre> |
| 1983 |
</td> |
| 1984 |
<td> |
| 1985 |
<p>Write unpaired reads that fail to align to file at |
| 1986 |
<code><path></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 <path> |
| 2001 |
--al-gz <path> |
| 2002 |
--al-bz2 <path> |
| 2003 |
--al-lz4 <path></code></pre> |
| 2004 |
</td> |
| 2005 |
<td> |
| 2006 |
<p>Write unpaired reads that align at least once to file at |
| 2007 |
<code><path></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 <path> |
| 2022 |
--un-conc-gz <path> |
| 2023 |
--un-conc-bz2 <path> |
| 2024 |
--un-conc-lz4 <path></code></pre> |
| 2025 |
</td> |
| 2026 |
<td> |
| 2027 |
<p>Write paired-end reads that fail to align concordantly to file(s) at |
| 2028 |
<code><path></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><path></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><path></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 <path> |
| 2046 |
--al-conc-gz <path> |
| 2047 |
--al-conc-bz2 <path> |
| 2048 |
--al-conc-lz4 <path></code></pre> |
| 2049 |
</td> |
| 2050 |
<td> |
| 2051 |
<p>Write paired-end reads that align concordantly at least once to |
| 2052 |
file(s) at <code><path></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><path></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><path></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 <path></code></pre> |
| 2079 |
</td> |
| 2080 |
<td> |
| 2081 |
<p>Write <code>bowtie2</code> metrics to file <code><path></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 <path></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 <int></code></pre> |
| 2105 |
</td> |
| 2106 |
<td> |
| 2107 |
<p>Write a new <code>bowtie2</code> metrics record every |
| 2108 |
<code><int></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 <text></code></pre> |
| 2144 |
</td> |
| 2145 |
<td> |
| 2146 |
<p>Set the read group ID to <code><text></code>. This causes the |
| 2147 |
SAM <code>@RG</code> header line to be printed, with |
| 2148 |
<code><text></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><text></code>.</p> |
| 2152 |
</td> |
| 2153 |
</tr> |
| 2154 |
<tr> |
| 2155 |
<td id="bowtie2-options-rg"> |
| 2156 |
<pre><code>--rg <text></code></pre> |
| 2157 |
</td> |
| 2158 |
<td> |
| 2159 |
<p>Add <code><text></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 <config></code></pre> |
| 2221 |
</td> |
| 2222 |
<td> |
| 2223 |
<p>Use <code><config></code> to toggle SAM Optional Fields where |
| 2224 |
<code><config></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 "-md,yp"</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 <int></code></pre> |
| 2240 |
</td> |
| 2241 |
<td> |
| 2242 |
<p>Override the offrate of the index with <code><int></code>. If |
| 2243 |
<code><int></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><int></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 <int></code></pre> |
| 2313 |
</td> |
| 2314 |
<td> |
| 2315 |
<p>Use <code><int></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:<N></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:<N></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:<N></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:<N></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:<N></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:<N></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:<N></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:<N></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:<S></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:<S></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:<S></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]* <reference_in> <bt2_base></code></pre> |
| 2657 |
<h3 id="main-arguments-1">Main arguments</h3> |
| 2658 |
<table> |
| 2659 |
<tr> |
| 2660 |
<td> |
| 2661 |
<pre><code><reference_in></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><reference_in></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><bt2_base></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><bt2_base></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><reference_in></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><reference_in></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 <int></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 <int></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 <int></code></pre> |
| 2790 |
</td> |
| 2791 |
<td> |
| 2792 |
<p>Use <code><int></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 <int></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><int></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 <int></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><int></code> characters of |
| 2856 |
the query. A larger <code><int></code> yields a larger lookup |
| 2857 |
table but faster query times. The ftab has size |
| 2858 |
4^(<code><int></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 <int></code></pre> |
| 2865 |
</td> |
| 2866 |
<td> |
| 2867 |
<p>Use <code><int></code> as the seed for pseudo-random number |
| 2868 |
generator.</p> |
| 2869 |
</td> |
| 2870 |
</tr> |
| 2871 |
<tr> |
| 2872 |
<td> |
| 2873 |
<pre><code>--cutoff <int></code></pre> |
| 2874 |
</td> |
| 2875 |
<td> |
| 2876 |
<p>Index only the first <code><int></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 <int></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]* <bt2_base></code></pre> |
| 2933 |
<h3 id="main-arguments-2">Main arguments</h3> |
| 2934 |
<table> |
| 2935 |
<tr> |
| 2936 |
<td> |
| 2937 |
<pre><code><bt2_base></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 <int></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><int></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 <0 or 1> |
| 2979 |
SA-Sample 1 in <sample> |
| 2980 |
FTab-Chars <chars> |
| 2981 |
Sequence-1 <name> <len> |
| 2982 |
Sequence-2 <name> <len> |
| 2983 |
... |
| 2984 |
Sequence-N <name> <len></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 <filename></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 +"@6<:27(F&5)9"B):%B+A-%5A?2$HCB0B+0=D<7E/<.03#!.F77@6B==?C"7>;))%;,3-$.A06+<-1/@@?,26">=?*@'0;$:;??G+:#+(A?9+10!8!?()?7C> AS:i:-5 XN:i:0 XM:i:3 XO:i:0 XG:i:0 NM:i:3 MD:Z:59G13G21G26 YT:Z:UU |
| 3082 |
r2 0 gi|9626243|ref|NC_001416.1| 8886 42 275M * 0 0 NTTNTGATGCGGGCTTGTGGAGTTCAGCCGATCTGACTTATGTCATTACCTATGAAATGTGAGGACGCTATGCCTGTACCAAATCCTACAATGCCGGTGAAAGGTGCCGGGATCACCCTGTGGGTTTATAAGGGGATCGGTGACCCCTACGCGAATCCGCTTTCAGACGTTGACTGGTCGCGTCTGGCAAAAGTTAAAGACCTGACGCCCGGCGAACTGACCGCTGAGNCCTATGACGACAGCTATCTCGATGATGAAGATGCAGACTGGACTGC (#!!'+!$""%+(+)'%)%!+!(&++)''"#"#&#"!'!("%'""("+&%$%*%%#$%#%#!)*'(#")(($&$'&%+&#%*)*#*%*')(%+!%%*"$%"#+)$&&+)&)*+!"*)!*!("&&"*#+"&"'(%)*("'!$*!!%$&&&$!!&&"(*"$&"#&!$%'%"#)$#+%*+)!&*)+(""#!)!%*#"*)*')&")($+*%%)!*)!('(%""+%"$##"#+(('!*(($*'!"*('"+)&%#&$+('**$$&+*&!#%)')'(+(!%+ AS:i:-14 XN:i:0 XM:i:8 XO:i:0 XG:i:0 NM:i:8 MD:Z:0A0C0G0A108C23G9T81T46 YT:Z:UU |
| 3083 |
r3 16 gi|9626243|ref|NC_001416.1| 11599 42 338M * 0 0 GGGCGCGTTACTGGGATGATCGTGAAAAGGCCCGTCTTGCGCTTGAAGCCGCCCGAAAGAAGGCTGAGCAGCAGACTCAAGAGGAGAAAAATGCGCAGCAGCGGAGCGATACCGAAGCGTCACGGCTGAAATATACCGAAGAGGCGCAGAAGGCTNACGAACGGCTGCAGACGCCGCTGCAGAAATATACCGCCCGTCAGGAAGAACTGANCAAGGCACNGAAAGACGGGAAAATCCTGCAGGCGGATTACAACACGCTGATGGCGGCGGCGAAAAAGGATTATGAAGCGACGCTGTAAAAGCCGAAACAGTCCAGCGTGAAGGTGTCTGCGGGCGAT 7F$%6=$:9B@/F'>=?!D?@0(:A*)7/>9C>6#1<6:C(.CC;#.;>;2'$4D:?&B!>689?(0(G7+0=@37F)GG=>?958.D2E04C<E,*AD%G0.%$+A:'H;?8<72:88?E6((CF)6DF#.)=>B>D-="C'B080E'5BH"77':"@70#4%A5=6.2/1>;9"&-H6)=$/0;5E:<8G!@::1?2DC7C*;@*#.1C0.D>H/20,!"C-#,6@%<+<D(AG-).?&#0.00'@)/F8?B!&"170,)>:?<A7#1(A@0E#&A.*DC.E")AH"+.,5,2>5"2?:G,F"D0B8D-6$65D<D!A/38860.*4;4B<*31?6 AS:i:-22 XN:i:0 XM:i:8 XO:i:0 XG:i:0 NM:i:8 MD:Z:80C4C16A52T23G30A8T76A41 YT:Z:UU |
| 3084 |
r4 0 gi|9626243|ref|NC_001416.1| 40075 42 184M * 0 0 GGGCCAATGCGCTTACTGATGCGGAATTACGCCGTAAGGCCGCAGATGAGCTTGTCCATATGACTGCGAGAATTAACNGTGGTGAGGCGATCCCTGAACCAGTAAAACAACTTCCTGTCATGGGCGGTAGACCTCTAAATCGTGCACAGGCTCTGGCGAAGATCGCAGAAATCAAAGCTAAGT(=8B)GD04*G%&4F,1'A>.C&7=F$,+#6!))43C,5/5+)?-/0>/D3=-,2/+.1?@->;)00!'3!7BH$G)HG+ADC'#-9F)7<7"$?&.>0)@5;4,!0-#C!15CF8&HB+B==H>7,/)C5)5*+(F5A%D,EA<(>G9E0>7&/E?4%;#'92)<5+@7:A.(BG@[email protected] AS:i:-1 XN:i:0 XM:i:1 XO:i:0 XG:i:0 NM:i:1 MD:Z:77C106 YT:Z:UU |
| 3085 |
r5 0 gi|9626243|ref|NC_001416.1| 48010 42 138M * 0 0 GTCAGGAAAGTGGTAAAACTGCAACTCAATTACTGCAATGCCCTCGTAATTAAGTGAATTTACAATATCGTCCTGTTCGGAGGGAAGAACGCGGGATGTTCATTCTTCATCACTTTTAATTGATGTATATGCTCTCTT 9''%<D)A03E1-*7=),:F/0!6,D9:H,<9D%:0B(%'E,(8EFG$E89B$27G8F*2+4,-!,0D5()&=(FGG:5;3*@/.0F-G#5#3->('FDFEG?)5.!)"AGADB3?6(@H(:B<>6!>;>6>G,."?% AS:i:0 XN:i:0 XM:i:0 XO:i:0 XG:i:0 NM:i:0 MD:Z:138 YT:Z:UU |
| 3086 |
r6 16 gi|9626243|ref|NC_001416.1| 41607 42 72M2D119M * 0 0 TCGATTTGCAAATACCGGAACATCTCGGTAACTGCATATTCTGCATTAAAAAATCAACGCAAAAAATCGGACGCCTGCAAAGATGAGGAGGGATTGCAGCGTGTTTTTAATGAGGTCATCACGGGATNCCATGTGCGTGACGGNCATCGGGAAACGCCAAAGGAGATTATGTACCGAGGAAGAATGTCGCT 1H#G;H"$E*E#&"*)2%66?=9/9'=;4)4/>@%+5#@#$4A*!<D=="8#1*A9BA=:(1+#C&.#(3#H=9E)AC*5,AC#E'536*2?)H14?>9'B=7(3H/B:+A:8%1-+#(E%&$$&14"76D?>7(&20H5%*&CF8!G5B+A4F$7(:"'?0$?G+$)B-?2<0<F=D!38BH,%=8&5@+ AS:i:-13 XN:i:0 XM:i:2 XO:i:1 XG:i:2 NM:i:4 MD:Z:72^TT55C15A47 YT:Z:UU |
| 3087 |
r7 16 gi|9626243|ref|NC_001416.1| 4692 42 143M * 0 0 TCAGCCGGACGCGGGCGCTGCAGCCGTACTCGGGGATGACCGGTTACAACGGCATTATCGCCCGTCTGCAACAGGCTGCCAGCGATCCGATGGTGGACAGCATTCTGCTCGATATGGACANGCCCGGCGGGATGGTGGCGGGG -"/@*7A0)>2,AAH@&"%B)*5*23B/,)90.B@%=FE,E063C9?,:26$-0:,.,1849'4.;F>FA;76+5&$<C":$!A*,<B,<)@<'85D%C*:)30@85;?.B$05=@95DCDH<53!8G:F:B7/A.E':434> AS:i:-6 XN:i:0 XM:i:2 XO:i:0 XG:i:0 NM:i:2 MD:Z:98G21C22 YT:Z:UU</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 > 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 - > 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> |