Bowtie: an Ultrafast, Lightweight Short Read Aligner Bowtie Manual ============= What is Bowtie? --------------- Bowtie is an ultrafast, memory-efficient short read aligner geared toward quickly aligning large sets of short DNA sequences (reads) to large genomes. It aligns 35-base-pair reads to the human genome at a rate of 25 million reads per hour on a typical workstation. Bowtie indexes the genome with a Burrows-Wheeler index to keep its memory footprint small: for the human genome, the index is as small as 1.1 GB (using -z), and typically about 2.2 GB (not using -z) or 2.9 GB (for paired-end alignment). Bowtie supports alignment policies equivalent to Maq and SOAP but is substantially faster: about 35x faster than Maq and over 250x faster than SOAP when aligning 35-bp reads to the human genome. Multiple processor cores can be used simultaneously to achieve greater alignment speed. Bowtie's output format can be converted to the format used by Maq, allowing users to rapidly align reads with Bowtie then identify variations with Maq. The Bowtie tools run on the command line under Windows, Mac OS X, Linux, and Solaris. What isn't Bowtie? ------------------ Bowtie is not a general-purpose alignment tool like MUMmer, BLAST or Vmatch. Bowtie works best with short reads (though it supports reads up to 1024 bases in length) and is designed to be extremely fast for read sets where a) many of the reads have at least one good, valid alignment, b) many of the reads are relatively high-quality, and c) the number of alignments reported per read is small (close to 1). These criteria are generally satisfied in the context of mammalian resequencing projects, but less competitive running times may be observed in other contexts. Bowtie does not yet work in ABI "color space," and does not yet report gapped alignments. These features are future work. Obtaining Bowtie Binaries ------------------------- Obtain Bowtie binaries for your platform from the Download section of the Sourceforge project site. Binaries are currently available for Intel architectures (i386 and x86_64) running Linux, Windows, and Mac OS X. https://sourceforge.net/project/showfiles.php?group_id=236897&package_id=288231 Obtaining and Building Bowtie Sources ------------------------------------- Building Bowtie requires a GNU-like environment that includes GCC, GNU Make and other basics. It should be possible to build Bowtie on a vanilla Linux or Mac installation. Bowtie can also be built on Windows using Cygwin or MinGW (MinGW recommended). If building with MinGW, first install MinGW and MSYS (http://www.mingw.org/), the zlib library (http://cygwin.com/packages/mingw-zlib/), and the pthreads library (http://sourceware.org/pthreads-win32/). You may also need the GnuWin32 core (http://gnuwin32.sf.net/packages/coreutils.htm) and other utilities to drive the build process. Bowtie depends on code from Maq (http://maq.sf.net) and from the SeqAn library (http://www.seqan.de). However, all supporting code is included in the Bowtie source archive, so there is no need to download additional sources. Obtain Bowtie sources from the Download section of the Sourceforge project site: https://sourceforge.net/project/showfiles.php?group_id=236897&package_id=288231 Extract the sources, change to the directory where they were extracted, and build the Bowtie tools by running GNU make (usually with the command 'make', but sometimes with 'gmake') with no arguments. If building with MinGW, run GNU make from the MSYS environment. Due to the -p option, Bowtie needs the pthreads library to compile and run. To compile Bowtie without pthreads support (which disables the -p option), use 'make BOWTIE_PTHREADS=0'. Using the 'bowtie' Aligner -------------------------- The 'bowtie' aligner takes an index and a set of reads as input and outputs a list of alignments. Alignments are selected according to a combination of the -v/-n/-e/-l options (plus the -I/-X/--fr/--rf/--ff options for paired-end alignment), which define which alignments are legal, and the -k/-a/-m/--best/--strata options which define which and how many legal alignments should be reported. By default, Bowtie enforces an alignment policy equivalent to Maq's quality-aware policy (http://maq.sf.net) (-n 2 -l 28 -e 70), but it can also be made to enforce an end-to-end k-difference policy equivalent to SOAP's (http://soap.genomics.org.cn/) (-v 2). Bowtie is designed to be very fast for read sets where a) many of the reads have at least one good, valid alignment, b) many of the reads are relatively high-quality, c) the number of alignments reported per read is small (close to 1). These criteria are generally satisfied in the context of modern short-read analyses such as RNA-seq, ChIP-seq, other types of -seq, and especially mammalian genotyping (e.g. the 1000 Genomes Project). You may observe longer running times in other research contexts. If you find Bowtie's performance to be disappointingly slow, please try the hints described in the "High Performance Tips" section below. If Bowtie continues to be too slow, please contact us and tell us the nature of your research application and the parameters you are using to run Bowtie. We are eager to hear your feedback. A result of Bowtie's indexing strategy is that alignments involving one or more ambiguous reference characters ('N', '-', 'R', 'Y', etc.) are considered invalid by Bowtie, regardless of the alignment policy. This is true only for ambiguous characters in the reference; alignments involving ambiguous characters in the read are legal, subject to the alignment policy. Also, alignments that "fall off" the reference sequence are not considered legal by Bowtie, though some such alignments will become legal once gapped alignment is implemented. The process by which bowtie chooses an alignment to report is randomized in order to avoid "mapping bias" - the phenomenon whereby an aligner systematically fails to report a particular class of good alignments, causing spurious "holes" in the comparative assembly. Whenever bowtie reports a subset of the valid alignments that exist, it makes an effort to sample them randomly. This randomness flows from a simple seeded pseudo-random number generator and is "deterministic" in the sense that Bowtie will always produce the same results for the same read when run with the same initial "seed" value (see documentation for --seed option). In the default mode, bowtie can exhibit strand bias. Strand bias occurs when input reference and reads are such that (a) some reads align equally well to sites on the forward and reverse strands of the reference, and (b) the number of such sites on one strand is different from the number on the other strand. When this happens for a given read, bowtie effectively chooses one strand or the other with 50% probability, then reports a randomly-selected alignment for that read from among the sites on the selected strand. This tends to overassign alignments to the sites on the strand with fewer sites and underassign to sites on the strand with more sites. The effect is mitigated, though it may not be eliminated, when reads are longer or when paired- end reads are used. Running Bowtie in --best mode eliminates strand bias by forcing Bowtie to select one strand or the other with a probability that is proportional to the number of best sites on the strand. Gapped alignments are not currently supported, but we do plan to implement this in the future. Alignment in ABI "color space" is also not currently supported. Maq-like Policy --------------- When the -n option is specified (and it is by default), Bowtie determines which alignments are valid according to the following policy, which is equivalent to Maq's default policy: 1. Alignments may have no more than N mismatches in the first L bases on the high-quality end of the read. 2. The sum of the quality values at all mismatched positions may not exceed E (where each position has a quality value on a phred-like scale of 0 up to about 40). The N, L and E parameters are configured using Bowtie's -n, -l and -e options. The -n (Maq-like) option is mutually exclusive with the -v (end-to-end k-difference) option. If there are many possible alignments satisfying these criteria, Bowtie will prefer to report alignments with fewer mismatches and where the sum from criterion 2 is smaller. However, Bowtie does not guarantee that the reported alignment(s) are "best" in terms of the number of mismatches (i.e. the alignment "stratum") or in terms of the quality values at the mismatched positions unless the --best option is specified. Bowtie is about 1 to 2.5 times slower when --best is specified. Note that Maq internally rounds base qualities to the nearest 10 and rounds qualities greater than 30 to 30. To maintain compatibility with Maq, Bowtie does the same. Rounding can be suppressed with the --nomaqround option. Bowtie is not fully sensitive in -n 2 and -n 3 modes by default. In these modes Bowtie imposes a "backtracking limit" to limit effort spent trying to find valid alignments for low-quality reads that are unlikely to have any. This may cause bowtie to miss some legal 2- and 3-mismatch alignments. The limit is set to a reasonable default (125 without --best, 800 with --best), but the user may decrease or increase the limit using the --maxbts and/or -y options. -y mode is slow but guarantees full sensitivity. End-to-end k-difference Policy ------------------------------ The policy has one criterion: Alignments may have no more than V mismatches. Quality values are ignored. The number of mismatches permitted is configurable with the -v option. The -v (end-to-end) option is mutually exclusive with the -n (Maq-like) option. If there are many possible alignments satisfying this criterion, Bowtie will prefer to report alignments with fewer mismatches. However, for reads where the "best" alignment has one or more mismatches, Bowtie does not guarantee that the reported alignment(s) will be best unless the --best option is specified. Bowtie is typically about 1 to 2.5 times slower when --best is specified. Reporting Modes --------------- With the -k, -a, -m, --best and --strata options, Bowtie gives the user a great deal of flexibility in selecting which alignments get reported. Here we give a few examples that demonstrate a few ways they can be combined to achieve a desired result. All examples are using the e_coli index that comes packaged with Bowtie. Example 1: -a ------------- $ ./bowtie -a -v 2 e_coli --concise -c ATGCATCATGCGCCAT 1-:<0,148810,2> 1-:<0,2852852,1> 1-:<0,4930433,2> 1-:<0,905664,2> 1+:<0,1093035,2> Reported 5 alignments to 1 output stream(s) Specifying -a instructs bowtie to report all valid alignments, subject to the alignment policy: -v 2. In this case, bowtie finds 5 inexact hits in the E. coli genome; 1 hit (the 2nd one listed) has 1 mismatch and 4 hits have 2 mismatches. Note that they are not necessarily listed in best-to-worst order. Example 2: -k 3 --------------- $ ./bowtie -k 3 -v 2 e_coli --concise -c ATGCATCATGCGCCAT 1-:<0,148810,2> 1-:<0,2852852,1> 1-:<0,4930433,2> Reported 3 alignments to 1 output stream(s) Specifying -k 3 instructs bowtie to report up to 3 valid alignments. In this case, a total of 5 valid alignments exist (see Example 1); bowtie reports 3 out of those 5. -k can be set to any integer greater than 0. Example 3: -k 6 --------------- $ ./bowtie -k 6 -v 2 e_coli --concise -c ATGCATCATGCGCCAT 1-:<0,148810,2> 1-:<0,2852852,1> 1-:<0,4930433,2> 1-:<0,905664,2> 1+:<0,1093035,2> Reported 5 alignments to 1 output stream(s) Specifying -k 6 instructs bowtie to report up to 6 valid alignments. In this case, a total of 5 valid alignments exist, so bowtie reports all 5. Example 4: default (-k 1) ------------------------- $ ./bowtie -v 2 e_coli --concise -c ATGCATCATGCGCCAT 1-:<0,148810,2> Reported 1 alignments to 1 output stream(s) Leaving the reporting options at their defaults causes Bowtie to report the first valid alignment it encounters. Because --best was not specified, we are not guaranteed that bowtie will report the best alignment, and in this case it does not (the 1-mismatch alignment from the previous example would have been better). The default reporting mode is equivalent to -k 1. Example 5: -a --best -------------------- $ ./bowtie -a --best -v 2 e_coli --concise -c ATGCATCATGCGCCAT 1-:<0,2852852,1> 1+:<0,1093035,2> 1-:<0,905664,2> 1-:<0,148810,2> 1-:<0,4930433,2> Reported 5 alignments to 1 output stream(s) Specifying -a --best results in the same alignments being printed as if just -a had been specified, but they are guaranteed to be reported in best-to-worst order. Example 6: -a --best --strata ----------------------------- $ ./bowtie -a --best --strata -v 2 e_coli --concise \ -c ATGCATCATGCGCCAT 1-:<0,2852852,1> Reported 1 alignments to 1 output stream(s) Specifying --strata in addition to -a and --best causes Bowtie to report only those alignments in the best alignment "stratum". The alignments in the best stratum are those having the least number of mismatches (or mismatches just in the "seed" portion of the alignment in the case of -n mode). Note that if --strata is specified, --best must also be specified. Example 7: -a -m 3 ------------------ $ ./bowtie -a -m 3 -v 2 e_coli --concise -c ATGCATCATGCGCCAT No results Specifying -m 3 instructs bowtie to refrain from reporting any alignments for reads having more than 3 reportable alignments. The -m option is useful when the user would like to guarantee that reported alignments are "unique", for some definition of unique. Example 1 showed that the read has 5 reportable alignments when -a and -v 2 are specified, so the -m 3 limit causes bowtie to output no alignments. Example 8: -a -m 5 ------------------ $ ./bowtie -a -m 5 -v 2 e_coli --concise -c ATGCATCATGCGCCAT 1-:<0,148810,2> 1-:<0,2852852,1> 1-:<0,4930433,2> 1-:<0,905664,2> 1+:<0,1093035,2> Reported 5 alignments to 1 output stream(s) Specifying -m 5 instructs bowtie to refrain from reporting any alignments for reads having more than 5 reportable alignments. Since the read has exactly 5 reportable alignments, the -m 5 limit allows bowtie to print them as usual. Example 9: -a -m 3 --best --strata ---------------------------------- $ ./bowtie -a -m 3 --best --strata -v 2 e_coli --concise \ -c ATGCATCATGCGCCAT 1-:<0,2852852,1> Reported 1 alignments to 1 output stream(s) Specifying -m 3 instructs bowtie to refrain from reporting any alignments for reads having more than 3 reportable alignments. As we saw in Example 6, the read has only 1 reportable alignment when -a, --best and --strata are specified, so the -m 3 limit allows bowtie to print that alignment as usual. Intuitively, the -m option, when combined with the --best and --strata options, guarntees a principled, though somewhat weaker form of "uniqueness." A stronger form of uniqueness is enforced when -m is specified but --best --strata are not. Paired-end Alignment -------------------- Bowtie can align paired-end reads when paired read files are specified using the -1 and -2 options (for pairs of raw, FASTA, or FASTQ read files), or using the --12 option (for Tab-delimited read files). A valid paired-end alignment satisfies the following criteria: 1. Both mates have a valid alignment according to the alignment policy specified by the -v/-n/-e/-l options. 2. The relative orientation and position of the mates satisfy the constraints given by the -I/-X/--fr/--rf/--ff options. Policies governing which paired-end alignments are reported for a given read are specified using the -k, -a and -m options as usual. The --strata and --best options do not apply in paired-end mode. A paired-end alignment is reported as a pair of mate alignments, both on a separate line, where the alignment for each mate is formatted the same as an unpaired (singleton) alignment. The alignment for the mate that occurs closest to the beginning of the reference sequence (the "upstream" mate) is always printed before the alignment for the downstream mate. Reads files containing paired-end reads will sometimes name the reads according to whether they are the #1 or #2 mates by appending a "/1" or "/2" suffix to the read name. If no such suffix is present in Bowtie's input, the suffix will be added when Bowtie prints read names in alignments. Finding a valid paired-end alignment where both mates align to repetitive regions of the reference can be very time-consuming. By default, Bowtie avoids much of this cost by imposing a limit on the number of "tries" it makes to match an alignment for one mate with a nearby alignment for the other. The default limit is 100. This causes Bowtie to miss some valid paired-end alignments where both mates lie in repetitive regions, but the user may use the --pairtries or -y options to increase Bowtie's sensitivity as desired. Paired-end alignments where one mate's alignment is entirely contained within the other's are considered invalid. Because Bowtie uses an in-memory representation of the original reference string when finding paired-end alignments, its memory footprint is larger when aligning paired-end reads. For example, the human index has a memory footprint of about 2.2 GB in single-end mode and 2.9 GB in paired-end mode. High Performance Tips --------------------- Tip 1: Use 64-bit bowtie if possible The 64-bit version of Bowtie is substantially faster (usually more than 50% faster) than the 32-bit version, due to Bowtie's use of 64-bit arithmetic when searching both in the index and in the reference. If possible, download the 64-bit binaries for Bowtie and run them on a 64-bit machine. If you are building Bowtie from sources, you may need to pass the -m64 option to g++ to compile the 64-bit version; you can do this by supplying argument BITS=64 to the 'make' command; e.g.: 'make BITS=64 bowtie'. To determine whether your version of bowtie is 64-bit or 32-bit, run 'bowtie --version'. Tip 2: If your computer has multiple processors/cores, try -p The -p option causes Bowtie to launch parallel search threads. Each thread runs on a different processor/core and all threads find alignments in parallel, increasing alignment throughput by approximately a multiple of . Tip 3: If reporting many alignments per read, try tweaking 'bowtie-build --offrate' If you are using the -k, -a or -m options and Bowtie is reporting many alignments per read (an average of more than about 10 per read) and you have some physical memory to spare, then consider building an index with a denser SA sample. To build an index with a denser SA sample, specify a smaller --offrate value when running 'bowtie-build'. A denser SA sample leads to a larger index, but is also particularly effective at speeding up alignment when then number of alignments reported per read is large. For example, if the number of alignments per read is very large, decreasing the index's --offrate by 1 could as much as double alignment performance, and decreasing by 2 could quadruple alignment performance, etc. On the other hand, decreasing --offrate increases the size of the Bowtie index, both on disk and in memory when aligning reads. At the default --offrate of 5, the SA sample for the human genome occupies about 375 MB of memory when aligning reads. Decreasing the --offrate by 1 doubles the memory taken by the SA sample, and decreasing by 2 quadruples the memory taken, etc. Tip 4: If bowtie "thrashes", try tweaking 'bowtie --offrate' If 'bowtie' is very slow and consistently triggers more than a few page faults per second (as observed via top or vmstat on Mac/Linux, or via a tool like Process Explorer on Windows), then try giving bowtie the --offrate option with a larger value than the value used when building the index. For example, bowtie-build's default --offrate is 5 and all pre-built indexes available from the Bowtie website are built with --offrate 5; so if bowtie thrashes when querying such an index, try using 'bowtie --offrate 6'. If bowtie still thrashes, try 'bowtie --offrate 7', etc. A higher --offrate causes bowtie to use a sparser sample of the suffix-array than is stored in the index; this saves memory but makes alignment reporting slower (which is especially slow when using -a or large -k). A note from firsthand experience: I have a MacBook Pro with 2 GB of RAM and I noticed that 'bowtie -z' would thrash and run very slowly when aligning reads against the pre-built human genome available from the Bowtie website. Using 'bowtie -z --offrate 6' prevented the thrashing and allowed bowtie to run much faster. Command Line ------------ The following is a detailed description of the options used to control the 'bowtie' aligner: Usage: bowtie [options]* {-1 -2 | --12 | } [] The basename of the index to be searched. The basename is the name of any of the index files up to but not including the final .1.ebwt / .rev.1.ebwt / etc. bowtie looks for the specified index first in the current directory, then in the 'indexes' subdirectory under the directory where the currently-running 'bowtie' executable is located, then looks in the directory specified in the BOWTIE_INDEXES environment variable. Comma-separated list of files containing the #1 mates (filename usually includes "_1"), or, if -c is specified, the mate sequences themselves. E.g., this might be "flyA_1.fq,flyB_1.fq", or, if -c is given, this might be "GGTCATCCT,ACGGGTCGT". Sequences specified with this option must correspond file-for-file and read-for-read with those specified in . Reads may be a mix of different lengths. If "-" is specified, Bowtie will read the #1 mates from stdin. "-" is not compatible with "-z/--phased". Comma-separated list of files containing the #2 mates (filename usually includes "_2"), or, if -c is specified, the mate sequences themselves. E.g., this might be "flyA_2.fq,flyB_2.fq", or, if -c is given, this might be "GTATGCTG,AATTCAGGCTG". Sequences specified with this option must correspond file-for-file and read-for-read with those specified in . Reads may be a mix of different lengths. If "-" is specified, Bowtie will read the #2 mates from stdin. "-" is not compatible with "-z/--phased". Comma-separated list of files containing a mix of unpaired and paired-end reads in Tab-delimited format. Tab-delimited format is a 1-read-per-line format where unpaired reads consist of a read name, sequence and quality string each separated by tabs. A paired-end read consists of a read name, sequnce of the /1 mate, quality values of the /1 mate, sequence of the /2 mate, and quality values of the /2 mate separated by tabs. Quality values can be expressed using any of the scales supported in FASTQ files. Reads may be a mix of different lengths and paired-end and unpaired reads may be intermingled in the same file. If "-" is specified, Bowtie will read the Tab- delimited reads from stdin. A comma-separated list of files containing unpaired reads to be aligned, or, if -c is specified, the unpaired read sequences themselves. E.g., this might be "lane1.fq,lane2.fq,lane3.fq,lane4.fq", or, if -c is specified, this might be "GGTCATCCT,ACGGGTCGT". Reads may be a mix of different lengths. If "-" is specified, Bowtie gets the reads from stdin. "-" is not compatible with "-z/--phased". File to write alignments to. By default, alignments are written to stdout (the console), but a file must be specified if the -b/--binout option is also specified. Options: ======== Input: ------ -q The query input files (specified either as and , or as ) are FASTQ files (usually having extension .fq or .fastq). This is the default. See also: --solexa-quals and --integer-quals. -f The query input files (specified either as and , or as ) are FASTA files (usually having extension .fa, .mfa, .fna or similar). All quality values are assumed to be 40 on the Phred scale. -r The query input files (specified either as and , or as ) are Raw files: one sequence per line, without quality values or names. All quality values are assumed to be 40 on the Phred scale. -c The query sequences are given on command line. I.e. , and are comma-separated lists of reads rather than lists of read files. -s/--skip Skip (i.e. do not align) the first reads or pairs in the input. -u/--qupto Only align the first reads or read pairs from the input (after the -s/--skip reads or pairs have been skipped). Default: no limit. -5/--trim5 Trim bases from high-quality (left) end of each read before alignment (default: 0). -3/--trim3 Trim bases from low-quality (right) end of each read before alignment (default: 0). --phred33-quals Input qualities are ASCII chars equal to the Phred quality plus 33. Default: on. --phred64-quals Input qualities are ASCII chars equal to the Phred quality plus 64. Default: off. --solexa-quals Convert input qualities from solexa-scaled (which can be negative) to phred-scaled (which can't). The formula for conversion is phred-qual = 10 * log(1 + 10 ** (solexa-qual/10.0)) / log(10). This is usually the right option for use with (unconverted) reads emitted by GA Pipeline versions prior to 1.3. Default: off. --solexa1.3-quals Same as --phred64-quals. This is usually the right option for use with (unconverted) reads emitted by GA Pipeline version 1.3 or later. Default: off. --integer-quals Quality values are represented in the read input file as space-separated ASCII integers, e.g., "40 40 30 40...", rather than ASCII characters, e.g., "II?I...". Integers are treated as being on the Phred scale unless --solexa-quals is also specified. Default: off. Alignment: ---------- -n/--seedmms The maximum number of mismatches permitted in the "seed", which is the first 28 base pairs of the read by default (see -l/--seedlen). This may be 0, 1, 2 or 3 and the default is 2. -e/--maqerr The maximum permitted total of quality values at mismatched read positions. This total is also called the "quality-weighted hamming distance" or "Q-distance." This is analogous to the -e option for "maq map". The default is 70. Note that, like Maq, Bowtie rounds quality values to the nearest 10 and saturates at 30. -l/--seedlen The "seed length"; i.e., the number of bases on the high-quality end of the read to which the -n ceiling applies. The lowest permitted value for this parameter is 5. The default is 28. Depending on the length of the reference genome, Bowtie can become extremely slow as this parameter is adjusted downward. --nomaqround Maq accepts quality values in the Phred scale, but internally rounds quality values to the nearest 10 saturating at 30. By default, Bowtie imitates this behavior. Use --nomaqround to prevent this type of rounding in Bowtie. -v Forego the Maq-like alignment policy and use a SOAP-like alignment policy. I.e., report end-to- end alignments with at most mismatches. If -v is specified, base quality values and the -e, -l and -n options are ignored. -I/--minins The minimum insert size for valid paired-end alignments. E.g. if -I 60 is specified and a paired-end alignment consists of two 20-bp alignments in the appropriate orientation with a 20-bp gap between them, that alignment is considered valid (as long as -X is also satisfied). A 19-bp gap would not be valid in that case. If trimming options -3 or -5 are also used, the -I constraint is applied with respect to the untrimmed mates, not the trimmed mates. Default: 0. -X/--maxins The maximum insert size for valid paired-end alignments. E.g. if -X 100 is specified and a paired-end alignment consists of two 20-bp alignments in the proper orientation with a 60-bp gap between them, that alignment is considered valid (as long as -I is also satisfied). A 61-bp gap would not be valid in that case. If trimming options -3 or -5 are also used, the -X constraint is applied with respect to the untrimmed mates, not the trimmed mates. Default: 250. --fr/--rf/--ff The upstream/downstream mate orientations for a valid paired-end alignment against the forward reference strand. E.g., if --fr is specified and there is a candidate paired-end alignment where mate1 appears upstream of the reverse complement of mate2 and the insert length constraints are met, that alignment is valid. Also, if mate2 appears upstream of the reverse complement of mate1 and all other constraints are met, that too is valid. --rf likewise requires that an upstream mate1 be reverse-complemented and a downstream mate2 be forward-oriented. --ff requires both an upstream mate1 and a downstream mate2 to be forward-oriented. Default: --fr (appropriate for the Illumina short insert library). --nofw/--norc If --nofw is specified, Bowtie will not attempt to align against the forward reference strand. If --norc is specified, Bowtie will not attempt to align against the reverse-complement reference strand. For paired-end reads using --fr or --rf modes, --nofw and --norc apply to the forward and reverse-complement pair orientations. I.e. specifying --nofw and --fr will only find reads in the R/F orientation where mate 2 occurs upstream of mate 1 with respect to the forward reference strand. --maxbts The maximum number of backtracks permitted when aligning a read in -n 2 or -n 3 mode (default: 125 without --best, 800 with --best). A "backtrack" is the introduction of a speculative substitution into the alignment. Without this limit, the default parameters will sometimes require that 'bowtie' try 100s or 1,000s of backtracks to align a read, especially if the read has many low-quality bases and/or has no valid alignments, slowing bowtie down significantly. However, this limit may cause some valid alignments to be missed. Higher limits yield greater sensitivity at the expensive of longer running times. See also: -y/--tryhard. --pairtries For paired-end alignment, this is the maximum number of attempts Bowtie will make to match an alignment for one mate up with an alignment for the opposite mate. Most paired-end alignments require only a few such attempts, but pairs where both mates occur in highly repetitive regions of the reference can require significantly more. Setting this to a higher number allows Bowtie to find more paired-end alignments for repetitive pairs at the expense of speed. The default is 100. See also: -y/--tryhard. -y/--tryhard Try as hard as possible to find valid alignments when they exist, including paired-end alignments. This is equivalent to specifying very high values for the --maxbts and --pairtries options. This mode is generally MUCH SLOWER than the default settings, but can be useful for certain research problems. This mode is slower when (a) the reference is very repetitive, (b) the reads are low quality, or (c) not many reads have valid alignments. --chunkmbs The number of megabytes of memory a given thread is given to store path descriptors in --best mode. Best-first search must keep track of many paths at once to ensure it is always extending the path with the lowest cumulative cost. Bowtie tries to minimize the memory impact of the descriptors, but they can still grow very large in some cases. If you receive an error message saying that chunk memory has been exhausted in --best mode, try adjusting this parameter up to dedicate more memory to the descriptors. Default: 32. Reporting: ---------- -k Report up to valid alignments per read or pair (default: 1). Validity of alignments is determined by the alignment policy (combined effects of -n, -v, -l, and -e). If more than one valid alignment exists and the --best and --strata options are specified, then only those alignments belonging to the best alignment "stratum" (i.e. those with the fewest mismatches) will be reported. Bowtie is designed to be very fast for small -k but bowtie can become significantly slower as -k increases. If you would like to use Bowtie for larger values of -k, consider building an index with a denser suffix-array sample, i.e. specify a smaller '--offrate' when invoking 'bowtie-build' for the relevant index (see Performance Tips section for details). -a/--all Report all valid alignments per read or pair (default: off). Validity of alignments is determined by the alignment policy (combined effects of -n, -v, -l, and -e). If more than one valid alignment exists and the --best and --strata options are specified, then only those alignments belonging to the best alignment "stratum" (i.e. those with the fewest mismatches) will be reported. Bowtie is designed to be very fast for small -k but bowtie can become significantly slower if -a/--all is specified. If you would like to use Bowtie with -a, consider building an index with a denser suffix-array sample, i.e. specify a smaller '--offrate' when invoking 'bowtie-build' for the relevant index (see Performance Tips section for details). -m Suppress all alignments for a particular read or pair if more than reportable alignments exist for it. Reportable alignments are those that would be reported given the -n, -v, -l, -e, -k, -a, --best, and --strata options. Default: no limit. Bowtie is designed to be very fast for small -m but bowtie can become significantly slower for larger values of -m. If you would like to use Bowtie for larger values of -k, consider building an index with a denser suffix- array sample, i.e. specify a smaller '--offrate' when invoking 'bowtie-build' for the relevant index (see Performance Tips section for details). --best Make Bowtie guarantee that reported singleton alignments are "best" in terms of stratum (i.e. number of mismatches, or mismatches in the seed in the case of -n mode) and in terms of the quality values at the mismatched position(s). Stratum always trumps quality; e.g. a 1-mismatch alignment where the mismatched position has Phred quality 40 is preferred over a 2-mismatch alignment where the mismatched positions both have Phred quality 10. When --best is not specified, Bowtie may report alignments that are sub-optimal in terms of stratum and/or quality (though an effort is made to report the best alignment). --best mode also removes all strand bias. Note that --best does not affect which alignments are considered "valid" by Bowtie, only which valid alignments are reported by Bowtie. When --best is specified and multiple hits are allowed (via -k or -a), the alignments for a given read are guaranteed to appear in best-to-worst order in Bowtie's output. Bowtie is about 1-2.5 times slower when --best is specified. --strata If many valid alignments exist and are reportable (e.g. are not disallowed via the -k option) and they fall into more than one alignment "stratum", report only those alignments that fall into the best stratum. By default, Bowtie reports all reportable alignments regardless of whether they fall into multiple strata. When --strata is specified, --best must also be specified. Output: ------- --concise Print alignments in a concise format. Each line has format 'read_idx{-|+}:', where read_idx is the index of the read mapped, {-|+} is the orientation of the read, ref_idx is the index of the reference sequence aligned to, ref_off is the offset into the reference sequence, and mms is the number of mismatches in the alignment. Each alignment appears on a separate line. -b/--binout Output alignments in a concise binary format. If this is specified, must also be specified. -t/--time Print the amount of wall-clock time taken by each search phase and index turnover. -B/--offbase When outputting alignments, number the first base of a reference sequence as . Default: 0. (Default is likely to change to 1 in Bowtie 1.0.) --quiet Print nothing besides alignments. --refout Write alignments to a set of files named refXXXXX.map, where XXXXX is the 0-padded index of the reference sequence aligned to. This can be a useful way to break up work for downstream analyses when dealing with, for example, large numbers of reads aligned to the assembled human genome. If is also specified, it will be ignored. --refidx When a reference sequence is referred to in a reported alignment, refer to it by 0-based index (its offset into the list of references that were indexed) rather than by name. --al Write all reads for which at least one alignment was reported to a file with name . Written reads will appear as they did in the input, without any of the trimming or translation of quality values that may have taken place within Bowtie. Paired-end reads will be written to two parallel files with "_1" and "_2" inserted in the filename, e.g., if is aligned.fq, the #1 and #2 mates that fail to align will be written to aligned_1.fq and aligned_2.fq respectively. --un Write all reads that could not be aligned to a file with name . Written reads will appear as they did in the input, without any of the trimming or translation of quality values that may have taken place within Bowtie. Paired-end reads will be written to two parallel files with "_1" and "_2" inserted in the filename, e.g., if is unaligned.fq, the #1 and #2 mates that fail to align will be written to unaligned_1.fq and unaligned_2.fq respectively. Unless --max is also specified, reads with a number of valid alignments exceeding the limit set with the -m option are also written to . --max Write all reads with a number of valid alignments exceeding the limit set with the -m option to a file with name . Written reads will appear as they did in the input, without any of the trimming or translation of quality values that may have taken place within Bowtie. Paired-end reads will be written to two parallel files with "_1" and "_2" inserted in the filename, e.g., if is max.fq, the #1 and #2 mates that fail to align will be written to max_1.fq and max_2.fq respectively. These reads are not written to the file specified with --un. Performance: ------------ -p/--threads Launch parallel search threads (default: 1). Threads will run on separate processors/cores and synchronize when grabbing reads and outputting alignments. Searching for alignments is highly parallel, and speedup is fairly close to linear. Speedup suffers somewhat in -z mode because switching between indexes is a time-consuming serial operation. This option is only available if bowtie is linked with the pthreads library (i.e. if BOWTIE_PTHREADS=0 is not specified at build time). -z/--phased Alternate between using the forward and mirror indexes in a series of phases such that only one "half" of the index is resident in memory at one time. This uses about half the amount of memory as the default (which keeps both forward and mirror indexes resident in memory at once), but is somewhat slower, scales worse (see -p), and is incompatible with use of --best or -k greater than 1. It is also incompatible with paired-end alignment. -o/--offrate Override the offrate of the index with . If is greater than the offrate used to build the index, then some row markings are discarded when the index is read into memory. This reduces the memory footprint of the aligner but requires more time to calculate text offsets. must be greater than the value used to build the index. --mm Use memory-mapped I/O to load the index, rather than normal POSIX/C file I/O. Memory-mapping the index allows many concurrent bowtie processes on the same machine to share the same memory image of the index (i.e. you pay the memory overhead just once). This facilitates memory-efficient parallelization of Bowtie in situations where using -p is not desirable. Other: ------ --seed Use as the seed for pseudo-random number generator. --verbose Print verbose output (for debugging). --version Print version information and quit. -h/--help Print detailed description of tool and its options (from MANUAL). Default output -------------- The 'bowtie' aligner outputs each alignment on a separate line. Each line is a collection of 8 fields separated by tabs; from left to right, the fields are: 1. Name of read that aligned 2. Orientation of read in the alignment, '-' for reverse complement, '+' otherwise 3. Name of reference sequence where alignment occurs, or ordinal ID if no name was provided 4. 1-based offset into the forward reference strand where leftmost character of the alignment occurs 5. Read sequence (reverse-complemented if orientation is '-') 6. ASCII-encoded read qualities (reversed if orientation is '-'). The encoded quality values are on the Phred scale and the encoding is ASCII-offset by 33 (ASCII char '!'). 7. Number of other instances where the same read aligns against the same reference characters as were aligned against in this alignment. This is *not* the number of other places the read aligns with the same number of mismatches. The number in this column is generally not a good proxy for that number (e.g., the number in this column may be '0' while the number of other alignments with the same number of mismatches might be large). This column was previously described as "Reserved". 8. Comma-separated list of mismatch descriptors. If there are no mismatches in the alignment, this field is empty. A single descriptor has the format offset:reference-base>read-base. The offset is expressed as a 0-based offset from the high-quality (5') end of the read. Using the 'bowtie-build' Indexer -------------------------------- Use 'bowtie-build' to build a Bowtie index from a set of DNA sequences. bowtie-build outputs a set of 6 files with suffixes .1.ebwt, .2.ebwt, .3.ebwt, .4.ebwt, .rev.1.ebwt, and .rev.2.ebwt, where the prefix is the parameter supplied by the user on the command line. These files together constitute the index: they are all that is needed to align reads to the reference sequences. The original sequence files are no longer used by Bowtie once the index is built. Use of Karkkainen's blockwise algorithm (see reference #4 below) allows bowtie-build to trade off between running time and memory usage. bowtie-build has three options governing how it makes this trade: -p/--packed, --bmax/--bmaxdivn, and --dcv. By default, bowtie- build will automatically search for the settings that yield the best running time without exhausting memory. This behavior can be disabled using the -a/--noauto option. The indexer provides options pertaining to the "shape" of the index, e.g. --offrate governs the fraction of Burrows-Wheeler rows that are "marked" (i.e., the "density" of the suffix-array sample; see reference #2). All of these options are potentially profitable trade- offs depending on the application. They have been set to defaults that are reasonable for most cases according to our experiments. See "High Performance Tips" in the "Using the 'bowtie' Aligner" section for additional details. Because bowtie-build uses 32-bit pointers internally, it can handle up to a maximum of 2^32-1 (somewhat more than 4 billion) characters in an index. If your reference exceeds 2^32-1 characters, bowtie-build will print an error message and abort. To resolve this, divide your reference sequences into smaller batches and/or chunks and build a separate index for each. If your computer has more than 3-4 GB of memory and you would like to exploit that fact to make index building faster, you must use a 64-bit version of the bowtie-build binary. The 32-bit version of the binary is restricted to using less than 4 GB of memory. If a 64-bit pre- built binary does not yet exist for your platform on the sourceforge download site, you will need to build one from source. The Bowtie index is based on the FM Index of Ferragina and Manzini, which in turn is based on the Burrows-Wheeler transform. The algorithm used to build the index is based on the blockwise algorithm of Karkkainen. For more information on these techniques, see these references: 1. Burrows M, Wheeler DJ: A block sorting lossless data compression algorithm. Digital Equipment Corporation, Palo Alto, CA 1994, Technical Report 124. 2. Ferragina, P. and Manzini, G. 2000. Opportunistic data structures with applications. In Proceedings of the 41st Annual Symposium on Foundations of Computer Science (November 12 - 14, 2000). FOCS 3. Ferragina, P. and Manzini, G. 2001. An experimental study of an opportunistic index. In Proceedings of the Twelfth Annual ACM-SIAM Symposium on Discrete Algorithms (Washington, D.C., United States, January 07 - 09, 2001). 269-278. 4. Karkkainen, J. 2007. Fast BWT in small space by blockwise suffix sorting. Theor. Comput. Sci. 387, 3 (Nov. 2007), 249-257 Command Line ------------ Usage: bowtie-build [options]* A comma-separated list of FASTA files containing the reference sequences to be aligned to, or, if -c is specified, the sequences themselves. E.g., this might be "chr1.fa,chr2.fa,chrX.fa,chrY.fa", or, if -c is specified, this might be "GGTCATCCT,ACGGGTCGT,CCGTTCTATGCGGCTTA". The basename of the index files to write. By default, bowtie-build writes files named NAME.1.ebwt, NAME.2.ebwt, NAME.3.ebwt, NAME.4.ebwt, NAME.rev.1.ebwt, and NAME.rev.2.ebwt, where NAME is the basename. Options: -f The reference input files (specified as ) are FASTA files (usually having extension .fa, .mfa, .fna or similar). -c The reference sequences are given on the command line. I.e. is a comma-separated list of sequences rather than a list of FASTA files. -a/--noauto Disable the default behavior whereby bowtie-build automatically selects values for --bmax/--dcv/--packed parameters according to the memory available. User may specify values for those parameters. If memory is exhausted during indexing, an error message will be printed; it is up to the user to try new parameters. -p/--packed Use a packed (2-bits-per-nucleotide) representation for DNA strings. This saves memory but makes indexing 2-3 times slower. Default: off. This is configured automatically by default; use -a/--noauto to configure manually. --bmax The maximum number of suffixes allowed in a block. Allowing more suffixes per block makes indexing faster, but increases memory overhead. Overrides any previous specification of --bmax, --bmaxmultsqrt or --bmaxdivn. Default: --bmaxdivn 4. This is configured automatically by default; use -a/--noauto to configure manually. --bmaxdivn The maximum number of suffixes allowed in a block, expressed as a fraction of the length of the reference. Overrides any previous specification of --bmax, --bmaxmultsqrt or --bmaxdivn. Default: --bmaxdivn 4. This is configured automatically by default; use -a/--noauto to configure manually. --dcv Use as the period for the difference- cover sample. A larger period yields less memory overhead, but may make suffix sorting slower, especially if repeats are present. Must be a power of 2 no greater than 4096. Default: 1024. This is configured automatically by default; use -a/--noauto to configure manually. --nodc Disable use of the difference-cover sample. Suffix sorting becomes quadratic-time in the worst case (where the worst case is an extremely repetitive reference). Default: off. -r/--noref Do not build the NAME.3.ebwt and NAME.4.ebwt portions of the index, which contain a bitpacked version of the reference sequences and are (currently) only used for paired-end alignment. -3/--justref Build *only* the NAME.3.ebwt and NAME.4.ebwt portions of the index, which contain a bitpacked version of the reference sequences and are (currently) only used for paired-end alignment. -o/--offrate To map alignments back to positions on the reference sequences, it's necessary to annotate ("mark") some or all of the Burrows-Wheeler rows with their corresponding location on the genome. The offrate governs how many rows get marked: the indexer will mark every 2^ rows. Marking more rows makes reference-position lookups faster, but requires more memory to hold the annotations at runtime. The default is 5 (every 32nd row is marked; for human genome, annotations occupy about 340 megabytes). -t/--ftabchars The ftab is the lookup table used to calculate an initial Burrows-Wheeler range with respect to the first characters of the query. A larger yields a larger lookup table but faster query times. The ftab has size 4^(+1) bytes. The default is 10 (ftab is 4MB). --ntoa Convert Ns in the reference sequence to As before building the index. By default, Ns are simply excluded from the index and 'bowtie' will not find alignments that overlap them. --big --little Endianness to use when serializing integers to the index file. Default: little-endian (recommended for Intel- and AMD-based architectures). --seed Use as the seed for pseudo-random number generator. --cutoff Index only the first bases of the reference sequences (cumulative across sequences) and ignore the rest. --oldpmap bowtie-build switched schemes for mapping "joined" reference locations to original reference locations in version 0.9.8. The new scheme has the advantage that it does not use padding. This option activates the old padding-based scheme used in versions prior to 0.9.8. Versions of 'bowtie' prior to 0.9.8 can query only indexes that use the old scheme. Version of 'bowtie' starting with 0.9.8 can query indexes using either scheme. This option will be deprecated in version 1.0. -q/--quiet bowtie-build is verbose by default. With this option ebwt-build will print only error messages. -h/--help Print detailed description of tool and its options (from MANUAL). --version Print version information and quit. Using the 'bowtie-maptool' Alignment Converter ---------------------------------------------- 'bowtie-maptool' allows the user to convert between alignment formats generated by Bowtie. It is most useful for converting from Bowtie's compact binary output format (-b/--binout), which is most appropriate for archiving large sets of alignments, to Bowtie's more verbose tab- delimited human-readable format (Bowtie's default output). It can also be used to sort a set of alignments with respect to the alignments' position on the reference (-s/--sort). This is a necessary first step to most analyses, including consensus and SNP calling. At this time, to sort triggered by the -s/--sort option occurs entirely in memory, so sorting very large sets of reads may exhaust memory. For information about converting Bowtie alignment to Maq's .map format, see the next section on using 'bowtie-maqconvert'. Command Line ------------ Usage: bowtie-maptool [options]* [] Alignment file output by bowtie to be converted, or "-" to convert alignments from stdin. [] Converted alignment file to output. Default: write alignments to stdout. must be specified when -B/--outbin is used. Options: -d/--indef is in Bowtie's default tab-delimited, human-readable output format. -b/--inbin is in Bowtie's compact binary (-b/--binout) format (default). -D/--outdef will be in Bowtie's default tab- delimited, human-readable output format (default). -B/--outbin will be in Bowtie's compact binary (-b/--binout) format. -C/--outconcise will be in Bowtie's --concise format. -Q/--outfastq will consist of aligned reads in FASTQ format. -F/--outfasta will consist of aligned reads in FASTA format. -s/--sort Sort hits by reference position before outputting. Sorts first by referene sequence (sequences that appeared earlier in the input have priority), then by offset into the sequence (alignments appearing closer to the left-hand end of the sequence have priority). -v/--verbose Print verbose output (for debugging). -h/--help Print detailed description of tool and its options (from MANUAL). --version Print version information and quit. Using the 'bowtie-maqconvert' Alignment Converter ------------------------------------------------- 'bowtie-maqconvert' allows the user to convert from Bowtie's default alignment format to the format used by Maq. This is a necessary first step to using Maq's analyses to study Bowtie's output, including consensus ('maq assemble') and SNP calling ('maq cns2snp'). Please note that, because Bowtie does not mimic Maq's exact calculation for alignment "mapping quality," results obtained by feeding Bowtie alignments to the Maq tools will generally be less accurate than those obtained using Maq's own aligner with the Maq tools. The conversion process includes an in-memory sort of all alignments with respect to their position on the reference. This can be problematic for very large sets of alignments; sorting so many alignments may exhaust memory, causing bowtie-maqconvert to crash or run very slowly. One solution is to split alignments into batches and use 'maq mapmerge' to combine outputs from bowtie-maqconvert. Another solution, depending on your application and reference sequences, may be to use bowtie's --refout option at alignment time to pre-partition alignments into separate files according to the reference sequence aligned against. Note that Maq changed its output format as of version 0.7.0 in order to accomodate read lengths up to 127 bases. Be sure to use the -o option of bowtie-maqconvert if you plan to use the results with a Maq version prior to 0.7.0. Command Line ------------ Usage: bowtie-maqconvert [options]* An alignments file generated by Bowtie. Need not have any particular extension. Name of Maq alignment file to output. Need not have any particular extension. The .bfa version of the reference sequences(s). Use 'maq fasta2bfa' to build this. It must be built using the exact same reference sequences as were used to build the Bowtie index. Options: -o Output uses Maq's old (pre-0.7.0) format. -v Print verbose output (for debugging). -h/-? Print detailed description of tool and its options (from MANUAL). Using the 'bowtie-inspect' Index Inspector ------------------------------------------ 'bowtie-inspect' extracts information from a Bowtie index about the original reference sequences used to build it. By default, the tool will output a FASTA file containing the sequences of the original references (with all non-A/C/G/T characters converted to Ns). It can also be used to extract just the reference sequence names using the -n option. Command Line ------------ Usage: bowtie-inspect [options]* The basename of the index to be inspected. The basename is the name of any of the four index files up to but not including the first period. bowtie first looks in the current directory for the index files, then looks in the 'indexes' subdirectory under the directory where the currently-running 'bowtie' executable is located, then looks in the directory specified in the BOWTIE_INDEXES environment variable. Options: -a/--across When printing FASTA output, output a newline character every bases (default: 60). -n/--names Print reference sequence names only; ignore sequence. -v/--verbose Print verbose output (for debugging). --version Print version information and quit. -h/--help Print detailed description of tool and its options (from MANUAL).