Bowtie2

Bowtie2 Overview

Bowtie2 is an ultrafast and memory-efficient tool for aligning sequencing reads to long reference sequences. It is particularly good at aligning reads of about 50 up to 100s or 1,000s of characters to relatively long (e.g. mammalian) genomes. Bowtie 2 supports gapped, local, and paired-end alignment modes. Galaxy wrapper for Bowtie 2 outputs alignments in BAM format, enabling interoperation with a large number of other tools available at this site. Majority of information in this page is derived from an excellent Bowtie2 manual written by Ben Langmead.

Selecting reference genomes for Bowtie2

Galaxy wrapper for Bowtie2 allows you select between precomputed and user-defined indices for reference genomes using Will you select a reference genome from your history or use a built-in index? flag. This flag has two options:

1. Use a built-in genome index - when selected (this is default), Galaxy provides the user with Select reference genome index dropdown. Genomes listed in this dropdown have been pre-indexed with bowtie2-build utility and are ready to be mapped against.
2. Use a genome from the history and build index - when selected, Galaxy provides the user with Select reference genome sequence dropdown. This dropdown is populated by all FASTA formatted files listed in your current history. If your genome of interest is uploaded into history it will be shown there. Selecting a genome from this dropdown will cause Galaxy to first transparently index it using bowtie2-build command, and then run mapping with bowtie2.

If your genome of interest is not listed here you have two choices:

1. Contact galaxy team using Help->Support link at the top of the interface and let us know that an index needs to be added
2. Upload your genome of interest as a FASTA file to Galaxy history and selected Use a genome from the history and build index option.

Bowtie2 options

Galaxy wrapper for Bowtie2 implements most but not all options available through the command line. Supported options are described below.

Inputs

Bowtie 2 accepts files in Sanger FASTQ format (single or paired-end). Paired-end data can represented as two individual (forward and reverse) datasets, as well as a single interleaved dataset (see an example at the end of the help section).

Input options:

--interleaved
        Reads interleaved FASTQ files where the first two records (8 lines) represent a mate pair.

-s/--skip <int>
        Skip (i.e. do not align) the first `<int>` reads or pairs in the input.

-u/--qupto <int>
        Align the first `<int>` reads or read pairs from the input (after the
        `-s`/`--skip` reads or pairs have been skipped), then stop.  Default: no limit.

-5/--trim5 <int>
        Trim `<int>` bases from 5' (left) end of each read before alignment (default: 0).

-3/--trim3 <int>
        Trim `<int>` bases from 3' (right) end of each read before alignment (default: 0).

--phred33
        Input qualities are ASCII chars equal to the Phred quality plus 33.  This is
        also called the "Phred+33" encoding, which is used by the very latest Illumina
        pipelines.

--phred64
        Input qualities are ASCII chars equal to the Phred quality plus 64.  This is
        also called the "Phred+64" encoding.

--solexa-quals
        Convert input qualities from Solexa Phred quality (which can be negative) to
        Phred Phred quality (which can't).  This scheme was used in older Illumina GA
        Pipeline versions (prior to 1.3).  Default: off.

--int-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 quality scale unless
        `--solexa-quals` is also specified. Default: off.

Presets in `--end-to-end` mode:

--very-fast
        Same as: `-D 5 -R 1 -N 0 -L 22 -i S,0,2.50`

--fast
        Same as: `-D 10 -R 2 -N 0 -L 22 -i S,0,2.50`

--sensitive
        Same as: `-D 15 -R 2 -L 22 -i S,1,1.15` (default in `--end-to-end` mode)

--very-sensitive
        Same as: `-D 20 -R 3 -N 0 -L 20 -i S,1,0.50`

Presets options in `--local` mode:

--very-fast-local
        Same as: `-D 5 -R 1 -N 0 -L 25 -i S,1,2.00`

--fast-local
        Same as: `-D 10 -R 2 -N 0 -L 22 -i S,1,1.75`

--sensitive-local
        Same as: `-D 15 -R 2 -N 0 -L 20 -i S,1,0.75` (default in `--local` mode)

--very-sensitive-local
        Same as: `-D 20 -R 3 -N 0 -L 20 -i S,1,0.50`

Alignment options:

-N <int>
        Sets the number of mismatches to allowed in a seed alignment during multiseed
        alignment.  Can be set to 0 or 1. Setting this higher makes alignment slower
        (often much slower) but increases sensitivity.  Default: 0.

-L <int>
        Sets the length of the seed substrings to align during multiseed alignment.
        Smaller values make alignment slower but more sensitive. Default: the
        `--sensitive` preset is used by default, which sets `-L` to 22 in
        `--end-to-end` mode and to 20 in `--local` mode.

-i <func>
        Sets a function governing the interval between seed substrings to use during
        multiseed alignment.  For instance, if the read has 30 characers, and seed
        length is 10, and the seed interval is 6, the seeds extracted will be:

Read:      TAGCTACGCTCTACGCTATCATGCATAAAC
Seed 1 fw: TAGCTACGCT
Seed 1 rc: AGCGTAGCTA
Seed 2 fw:       CGCTCTACGC
Seed 2 rc:       GCGTAGAGCG
Seed 3 fw:             ACGCTATCAT
Seed 3 rc:             ATGATAGCGT
Seed 4 fw:                   TCATGCATAA
Seed 4 rc:                   TTATGCATGA

Since it's best to use longer intervals for longer reads, this parameter sets
the interval as a function of the read length, rather than a single
one-size-fits-all number.  For instance, specifying `-i S,1,2.5` sets the
interval function `f` to `f(x) = 1 + 2.5 * sqrt(x)`, where x is the read length.
If the function returns a result less than
1, it is rounded up to 1. Default: the `--sensitive` preset is used by
default, which sets `-i` to `S,1,1.15` in `--end-to-end` mode to `-i S,1,0.75`
in `--local` mode.

--n-ceil <func>
        Sets a function governing the maximum number of ambiguous characters (usually
        `N`s and/or `.`s) allowed in a read as a function of read length.  For instance,
        specifying `-L,0,0.15` sets the N-ceiling function `f` to `f(x) = 0 + 0.15 * x`,
        where x is the read length.  Reads exceeding this ceiling are filtered out.
        Default: `L,0,0.15`.

--dpad <int>
        "Pads" dynamic programming problems by `<int>` columns on either side to allow
        gaps.  Default: 15.

--gbar <int>
        Disallow gaps within `<int>` positions of the beginning or end of the read.
        Default: 4.

--ignore-quals
        When calculating a mismatch penalty, always consider the quality value at the
        mismatched position to be the highest possible, regardless of the actual value.
        I.e. input is treated as though all quality values are high.  This is also the
        default behavior when the input doesn't specify quality values (e.g. in `-f`,
        `-r`, or `-c` modes).

--nofw/--norc
        If `--nofw` is specified, `bowtie2` will not attempt to align unpaired reads to
        the forward (Watson) reference strand.  If `--norc` is specified, `bowtie2` will
        not attempt to align unpaired reads against the reverse-complement (Crick)
        reference strand. In paired-end mode, `--nofw` and `--norc` pertain to the
        fragments; i.e. specifying `--nofw` causes `bowtie2` to explore only those
        paired-end configurations corresponding to fragments from the reverse-complement
        (Crick) strand.  Default: both strands enabled.

--no-1mm-upfront
        By default, Bowtie 2 will attempt to find either an exact or a 1-mismatch
        end-to-end alignment for the read *before* trying the multiseed heuristic.  Such
        alignments can be found very quickly, and many short read alignments have exact or
        near-exact end-to-end alignments.  However, this can lead to unexpected
        alignments when the user also sets options governing the multiseed heuristic,
        like `-L` and `-N`.  For instance, if the user specifies `-N 0` and `-L` equal
        to the length of the read, the user will be surprised to find 1-mismatch alignments
        reported.  This option prevents Bowtie 2 from searching for 1-mismatch end-to-end
        alignments before using the multiseed heuristic, which leads to the expected
        behavior when combined with options such as `-L` and `-N`.  This comes at the
        expense of speed.

--end-to-end
        In this mode, Bowtie 2 requires that the entire read align from one end to the
        other, without any trimming (or "soft clipping") of characters from either end.
        The match bonus `--ma` always equals 0 in this mode, so all alignment scores
        are less than or equal to 0, and the greatest possible alignment score is 0.
        This is mutually exclusive with `--local`.  `--end-to-end` is the default mode.

--local
        In this mode, Bowtie 2 does not require that the entire read align from one end
        to the other.  Rather, some characters may be omitted ("soft clipped") from the
        ends in order to achieve the greatest possible alignment score.  The match bonus
        `--ma` is used in this mode, and the best possible alignment score is equal to
        the match bonus (`--ma`) times the length of the read.  Specifying `--local`
        and one of the presets (e.g. `--local --very-fast`) is equivalent to specifying
        the local version of the preset (`--very-fast-local`).  This is mutually
        exclusive with `--end-to-end`.  `--end-to-end` is the default mode.

Scoring options:

--ma <int>
        Sets the match bonus.  In `--local` mode `<int>` is added to the alignment
        score for each position where a read character aligns to a reference character
        and the characters match.  Not used in `--end-to-end` mode.  Default: 2.

--mp MX,MN
        Sets the maximum (`MX`) and minimum (`MN`) mismatch penalties, both integers.  A
        number less than or equal to `MX` and greater than or equal to `MN` is
        subtracted from the alignment score for each position where a read character
        aligns to a reference character, the characters do not match, and neither is an
        `N`.  If `--ignore-quals` is specified, the number subtracted quals `MX`.
        Otherwise, the number subtracted is `MN + floor( (MX-MN)(MIN(Q, 40.0)/40.0) )`
        where Q is the Phred quality value.  Default: `MX` = 6, `MN` = 2.

--np <int>
        Sets penalty for positions where the read, reference, or both, contain an
        ambiguous character such as `N`.  Default: 1.

--rdg <int1>,<int2>
        Sets the read gap open (`<int1>`) and extend (`<int2>`) penalties.  A read gap of
        length N gets a penalty of `<int1>` + N * `<int2>`.  Default: 5, 3.

--rfg <int1>,<int2>
        Sets the reference gap open (`<int1>`) and extend (`<int2>`) penalties.  A
        reference gap of length N gets a penalty of `<int1>` + N * `<int2>`.  Default:
        5, 3.

--score-min <func>
        Sets a function governing the minimum alignment score needed for an alignment to
        be considered "valid" (i.e. good enough to report).  This is a function of read
        length. For instance, specifying `L,0,-0.6` sets the minimum-score function `f`
        to `f(x) = 0 + -0.6 * x`, where `x` is the read length.  The default in `--end-to-end` mode is `L,-0.6,-0.6` and
        the default in `--local` mode is `G,20,8`.

Reporting options:

-k <int>
        By default, `bowtie2` searches for distinct, valid alignments for each read.
        When it finds a valid alignment, it continues looking for alignments that are
        nearly as good or better.  The best alignment found is reported (randomly
        selected from among best if tied).  Information about the best alignments is
        used to estimate mapping quality and to set SAM optional fields, such as
        `AS:i` and `XS:i`.

When `-k` is specified, however, `bowtie2` behaves differently.  Instead, it
searches for at most `<int>` distinct, valid alignments for each read.  The
search terminates when it can't find more distinct valid alignments, or when it
finds `<int>`, whichever happens first.  All alignments found are reported in
descending order by alignment score. The alignment score for a paired-end
alignment equals the sum of the alignment scores of the individual mates. Each
reported read or pair alignment beyond the first has the SAM 'secondary' bit
(which equals 256) set in its FLAGS field.  For reads that have more than
`<int>` distinct, valid alignments, `bowtie2` does not guarantee that the
`<int>` alignments reported are the best possible in terms of alignment score.
`-k` is mutually exclusive with `-a`.

Note: Bowtie 2 is not designed with large values for `-k` in mind, and when
aligning reads to long, repetitive genomes large `-k` can be very, very slow.

-a
        Like `-k` but with no upper limit on number of alignments to search for.  `-a`
        is mutually exclusive with `-k`.

Note: Bowtie 2 is not designed with `-a` mode in mind, and when
aligning reads to long, repetitive genomes this mode can be very, very slow.

Effort options:

-D <int>
        Up to `<int>` consecutive seed extension attempts can "fail" before Bowtie 2
        moves on, using the alignments found so far.  A seed extension "fails" if it
        does not yield a new best or a new second-best alignment.  This limit is
        automatically adjusted up when -k or -a are specified.  Default: 15.

-R <int>
        `<int>` is the maximum number of times Bowtie 2 will "re-seed" reads with
        repetitive seeds. When "re-seeding," Bowtie 2 simply chooses a new set of reads
        (same length, same number of mismatches allowed) at different offsets and
        searches for more alignments.  A read is considered to have repetitive seeds if
        the total number of seed hits divided by the number of seeds that aligned at
        least once is greater than 300.  Default: 2.

Paired-end options:

-I/--minins <int>
        The minimum fragment length 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.

        The larger the difference between `-I` and `-X`, the slower Bowtie 2 will
        run.  This is because larger differences bewteen `-I` and `-X` require that
        Bowtie 2 scan a larger window to determine if a concordant alignment exists.
        For typical fragment length ranges (200 to 400 nucleotides), Bowtie 2 is very
        efficient.

        Default: 0 (essentially imposing no minimum)

-X/--maxins <int>
        The maximum fragment length 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.

        The larger the difference between `-I` and `-X`, the slower Bowtie 2 will
        run.  This is because larger differences bewteen `-I` and `-X` require that
        Bowtie 2 scan a larger window to determine if a concordant alignment exists.
        For typical fragment length ranges (200 to 400 nucleotides), Bowtie 2 is very
        efficient.

        Default: 500.

--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 mate 1 appears upstream of the reverse
        complement of mate 2 and the fragment length constraints (`-I` and `-X`) are
        met, that alignment is valid.  Also, if mate 2 appears upstream of the reverse
        complement of mate 1 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 mate 1
        and a downstream mate 2 to be forward-oriented.  Default: `--fr` (appropriate
        for Illumina's Paired-end Sequencing Assay).

--no-mixed
        By default, when `bowtie2` cannot find a concordant or discordant alignment for
        a pair, it then tries to find alignments for the individual mates.  This option
        disables that behavior.

--no-discordant
        By default, `bowtie2` looks for discordant alignments if it cannot find any
        concordant alignments.  A discordant alignment is an alignment where both mates
        align uniquely, but that does not satisfy the paired-end constraints
        (`--fr`/`--rf`/`--ff`, `-I`, `-X`).  This option disables that behavior.

--dovetail
        If the mates "dovetail", that is if one mate alignment extends past the
        beginning of the other such that the wrong mate begins upstream, consider that
        to be concordant.  Default: mates cannot dovetail in a concordant alignment.

--no-contain
        If one mate alignment contains the other, consider that to be non-concordant.
        Default: a mate can contain the other in a concordant alignment.

--no-overlap
        If one mate alignment overlaps the other at all, consider that to be
        non-concordant.  Default: mates can overlap in a concordant alignment.

SAM options:

--rg-id <text>
        Set the read group ID to `<text>`.  This causes the SAM `@RG` header line to be
        printed, with `<text>` as the value associated with the `ID:` tag.  It also
        causes the `RG:Z:` extra field to be attached to each SAM output record, with
        value set to `<text>`.

--rg <text>
        Add `<text>` (usually of the form `TAG:VAL`, e.g. `SM:Pool1`) as a field on the
        `@RG` header line.  Note: in order for the `@RG` line to appear, `--rg-id`
        must also be specified.  This is because the `ID` tag is required by the SAM
        Specification.  Specify `--rg` multiple times to set multiple fields.  See the
        SAM Specification for details about what fields are legal.

--omit-sec-seq
        When printing secondary alignments, Bowtie 2 by default will write out the `SEQ`
        and `QUAL` strings.  Specifying this option causes Bowtie 2 to print an asterix
        in those fields instead.

Other options:

--reorder
        Guarantees that output SAM records are printed in an order corresponding to the
        order of the reads in the original input file, even when `-p` is set greater
        than 1.  Specifying `--reorder` and setting `-p` greater than 1 causes Bowtie
        2 to run somewhat slower and use somewhat more memory then if `--reorder` were
        not specified.  Has no effect if `-p` is set to 1, since output order will
        naturally correspond to input order in that case.

--seed <int>
        Use `<int>` as the seed for pseudo-random number generator.  Default: 0.

--non-deterministic
        Normally, Bowtie 2 re-initializes its pseudo-random generator for each read.  It
        seeds the generator with a number derived from (a) the read name, (b) the
        nucleotide sequence, (c) the quality sequence, (d) the value of the `--seed`
        option. This means that if two reads are identical (same name, same
        nucleotides, same qualities) Bowtie 2 will find and report the same alignment(s)
        for both, even if there was ambiguity.  When `--non-deterministic` is specified,
        Bowtie 2 re-initializes its pseudo-random generator for each read using the
        current time.  This means that Bowtie 2 will not necessarily report the same
        alignment for two identical reads.  This is counter-intuitive for some users,
        but might be more appropriate in situations where the input consists of many
        identical reads.

Paired-end (and mate-pair) data in fastq format

Paired end datasets can be represented as two individual datasets:

First dataset:

@1/1
AGGGATGTGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTA
+
EGGEGGGDFGEEEAEECGDEGGFEEGEFGBEEDDECFEFDD@CDD<ED
@2/1
AGGGATGTGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTA
+
HHHHHHEGFHEEFEEHEEHHGGEGGGGEFGFGGGGHHHHFBEEEEEFG

Second dataset:

@1/2
CCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAAC
+
GHHHDFDFGFGEGFBGEGGEGEGGGHGFGHFHFHHHHHHHEF?EFEFF
@2/2
CCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAAC
+
HHHHHHHHHHHHHGHHHHHHGHHHHHHHHHHHFHHHFHHHHHHHHHHH

Or a single interleaved dataset:

@1/1
AGGGATGTGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTA
+
EGGEGGGDFGEEEAEECGDEGGFEEGEFGBEEDDECFEFDD@CDD<ED
@1/2
CCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAAC
+
GHHHDFDFGFGEGFBGEGGEGEGGGHGFGHFHFHHHHHHHEF?EFEFF
@2/1
AGGGATGTGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTAGGGTTA
+
HHHHHHEGFHEEFEEHEEHHGGEGGGGEFGFGGGGHHHHFBEEEEEFG
@2/2
CCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAACCCTAAC
+
HHHHHHHHHHHHHGHHHHHHGHHHHHHHHHHHFHHHFHHHHHHHHHHH