An Introduction to Rbowtie2 (2024)

Build Bowtie2 Index

Before aligning reads, bowtie2 index should be build. refs is a character vector of fasta reference file paths. A prefix of bowtie index should be set to argument bt2Index. Then, 6 index files with .bt2 file name extension will be created with bt2Index prefix.

td <- tempdir()refs <- dir(system.file(package="Rbowtie2", "extdata", "bt2","refs"),full=TRUE)(cmdout<-bowtie2_build(references=refs, bt2Index=file.path(td, "lambda_virus"), "--threads 4 --quiet", overwrite=TRUE))

## arguments 'show.output.on.console', 'minimized' and 'invisible' are for Windows only

## character(0)

Additional Arguments of Bowtie Build

If you need to set additional arguments like “–threads 4 –quiet” above, you can call function below to print all options available. The fixed arguments references, bt2Index are invalid.

bowtie2_build_usage()

## arguments 'show.output.on.console', 'minimized' and 'invisible' are for Windows only

## [1] "Bowtie 2 version 2.4.4 by Ben Langmead (langmea@cs.jhu.edu, www.cs.jhu.edu/~langmea)"## [2] "Usage: bowtie2-build [options]* <reference_in> <bt2_index_base>" ## [3] " reference_in comma-separated list of files with ref sequences" ## [4] " bt2_index_base write bt2 data to files with this dir/basename" ## [5] "*** Bowtie 2 indexes work only with v2 (not v1). Likewise for v1 indexes. ***" ## [6] "Options:" ## [7] " -f reference files are Fasta (default)" ## [8] " -c reference sequences given on cmd line (as" ## [9] " <reference_in>)" ## [10] " --large-index force generated index to be 'large', even if ref" ## [11] " has fewer than 4 billion nucleotides" ## [12] " --debug use the debug binary; slower, assertions enabled" ## [13] " --sanitized use sanitized binary; slower, uses ASan and/or UBSan" ## [14] " --verbose log the issued command" ## [15] " -a/--noauto disable automatic -p/--bmax/--dcv memory-fitting" ## [16] " -p/--packed use packed strings internally; slower, less memory" ## [17] " --bmax <int> max bucket sz for blockwise suffix-array builder" ## [18] " --bmaxdivn <int> max bucket sz as divisor of ref len (default: 4)" ## [19] " --dcv <int> diff-cover period for blockwise (default: 1024)" ## [20] " --nodc disable diff-cover (algorithm becomes quadratic)" ## [21] " -r/--noref don't build .3/.4 index files" ## [22] " -3/--justref just build .3/.4 index files" ## [23] " -o/--offrate <int> SA is sampled every 2^<int> BWT chars (default: 5)" ## [24] " -t/--ftabchars <int> # of chars consumed in initial lookup (default: 10)" ## [25] " --threads <int> # of threads" ## [26] " --seed <int> seed for random number generator" ## [27] " -q/--quiet verbose output (for debugging)" ## [28] " -h/--help print detailed description of tool and its options" ## [29] " --usage print this usage message" ## [30] " --version print version information and quit"

Bowtie2 Alignment

The variable reads_1 and reads_1 are preprocessed reads file paths. With bowtie2 index, reads will be mapped to reference by calling bowtie2. The result is saved in a sam file whose path is set to output

reads_1 <- system.file(package="Rbowtie2", "extdata", "bt2", "reads", "reads_1.fastq")reads_2 <- system.file(package="Rbowtie2", "extdata", "bt2", "reads", "reads_2.fastq")if(file.exists(file.path(td, "lambda_virus.1.bt2"))){ (cmdout<-bowtie2_samtools(bt2Index = file.path(td, "lambda_virus"), output = file.path(td, "result"), outputType = "sam", seq1=reads_1, seq2=reads_2, overwrite=TRUE, bamFile = NULL, "--threads 3")) head(readLines(file.path(td, "result.sam")))}

## arguments 'show.output.on.console', 'minimized' and 'invisible' are for Windows only

## [1] "@HD\tVN:1.0\tSO:unsorted" ## [2] "@SQ\tSN:gi|9626243|ref|NC_001416.1|\tLN:48502" ## [3] "@PG\tID:bowtie2\tPN:bowtie2\tVN:2.4.4\tCL:\"/tmp/RtmpUxBONc/Rinstfc76268195eef/Rbowtie2/bowtie2-align-s --wrapper basic-0 --threads 3 -x /tmp/RtmpqMpVur/lambda_virus -S /tmp/RtmpqMpVur/result.sam -1 /tmp/RtmpUxBONc/Rinstfc76268195eef/Rbowtie2/extdata/bt2/reads/reads_1.fastq -2 /tmp/RtmpUxBONc/Rinstfc76268195eef/Rbowtie2/extdata/bt2/reads/reads_2.fastq\"" ## [4] "r1\t99\tgi|9626243|ref|NC_001416.1|\t18401\t42\t122M\t=\t18430\t227\tTGAATGCGAACTCCGGGACGCTCAGTAATGTGACGATAGCTGAAAACTGTACGATAAACNGTACGCTGAGGGCAGAAAAAATCGTCGGGGACATTNTAAAGGCGGCGAGCGCGGCTTTTCCG\t+\"@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>\tAS:i:-5\tXN:i:0\tXM:i:3\tXO:i:0\tXG:i:0\tNM:i:3\tMD:Z:59G13G21G26\tYS:i:-4\tYT:Z:CP" ## [5] "r1\t147\tgi|9626243|ref|NC_001416.1|\t18430\t42\t198M\t=\t18401\t-227\tGTGACGATAGCTGAAAACTGTACGATAAACGGTACGCTGAGGGCGGAAAAAATCGTCGGGGACATNGTANAGGCGGCGAGCGCGGCTTTNCCGCGCCAGCGTGAAAGCAGTGTGGACTGGCCGTCAGGTACCCGTACTGTCACCGTGACCGATGACCATCCTTTTGATCGCCAGATAGTGGTGCTTCCGCTGACGTTN\tB+9+D)1\"7>:@=D&D0@:@7:10@;<CA9>('A5D*G0@>!6%+,B<(%@#+8$@$+!-1=1::@:;99E((>--9H>H))\"?8&4-9#C:E*#&?D@6!;6'-@&$3>2.11,?AG9?-:?CBA.?1#+!0$@?C'*=B#/&:F&/-,E<>-F#++)/B0:2!E;.D8&?9;+G/2;E=>*<5@94H8CA9&F$?&\tAS:i:-4\tXN:i:0\tXM:i:4\tXO:i:0\tXG:i:0\tNM:i:4\tMD:Z:65T3A19T107T0\tYS:i:-5\tYT:Z:CP" ## [6] "r2\t99\tgi|9626243|ref|NC_001416.1|\t8886\t42\t275M\t=\t8973\t275\tNTTNTGATGCGGGCTTGTGGAGTTCAGCCGATCTGACTTATGTCATTACCTATGAAATGTGAGGACGCTATGCCTGTACCAAATCCTACAATGCCGGTGAAAGGTGCCGGGATCACCCTGTGGGTTTATAAGGGGATCGGTGACCCCTACGCGAATCCGCTTTCAGACGTTGACTGGTCGCGTCTGGCAAAAGTTAAAGACCTGACGCCCGGCGAACTGACCGCTGAGNCCTATGACGACAGCTATCTCGATGATGAAGATGCAGACTGGACTGC\t(#!!'+!$\"\"%+(+)'%)%!+!(&++)''\"#\"#&#\"!'!(\"%'\"\"(\"+&%$%*%%#$%#%#!)*'(#\")(($&$'&%+&#%*)*#*%*')(%+!%%*\"$%\"#+)$&&+)&)*+!\"*)!*!(\"&&\"*#+\"&\"'(%)*(\"'!$*!!%$&&&$!!&&\"(*\"$&\"#&!$%'%\"#)$#+%*+)!&*)+(\"\"#!)!%*#\"*)*')&\")($+*%%)!*)!('(%\"\"+%\"$##\"#+(('!*(($*'!\"*('\"+)&%#&$+('**$$&+*&!#%)')'(+(!%+\tAS:i:-14\tXN:i:0\tXM:i:8\tXO:i:0\tXG:i:0\tNM:i:8\tMD:Z:0A0C0G0A108C23G9T81T46\tYS:i:-5\tYT:Z:CP"

Additional Arguments and Version of Bowtie2 Aligner

If you need to set additional arguments like “–threads 3” above, you can call function below to print all options available. The fixed arguments like bt2Index, samOutput and seq1 etc. are invalid.

bowtie2_usage()

## arguments 'show.output.on.console', 'minimized' and 'invisible' are for Windows only

## [1] "Bowtie 2 version 2.4.4 by Ben Langmead (langmea@cs.jhu.edu, www.cs.jhu.edu/~langmea)" ## [2] "Usage: " ## [3] " bowtie2 [options]* -x <bt2-idx> {-1 <m1> -2 <m2> | -U <r> | --interleaved <i> | -b <bam>} [-S <sam>]"## [4] "" ## [5] " <bt2-idx> Index filename prefix (minus trailing .X.bt2)." ## [6] " NOTE: Bowtie 1 and Bowtie 2 indexes are not compatible." ## [7] " <m1> Files with #1 mates, paired with files in <m2>." ## [8] " Could be gzip'ed (extension: .gz) or bzip2'ed (extension: .bz2)." ## [9] " <m2> Files with #2 mates, paired with files in <m1>." ## [10] " Could be gzip'ed (extension: .gz) or bzip2'ed (extension: .bz2)." ## [11] " <r> Files with unpaired reads." ## [12] " Could be gzip'ed (extension: .gz) or bzip2'ed (extension: .bz2)." ## [13] " <i> Files with interleaved paired-end FASTQ/FASTA reads" ## [14] " Could be gzip'ed (extension: .gz) or bzip2'ed (extension: .bz2)." ## [15] " <bam> Files are unaligned BAM sorted by read name." ## [16] " <sam> File for SAM output (default: stdout)" ## [17] "" ## [18] " <m1>, <m2>, <r> can be comma-separated lists (no whitespace) and can be" ## [19] " specified many times. E.g. '-U file1.fq,file2.fq -U file3.fq'." ## [20] "" ## [21] "Options (defaults in parentheses):" ## [22] "" ## [23] " Input:" ## [24] " -q query input files are FASTQ .fq/.fastq (default)" ## [25] " --tab5 query input files are TAB5 .tab5" ## [26] " --tab6 query input files are TAB6 .tab6" ## [27] " --qseq query input files are in Illumina's qseq format" ## [28] " -f query input files are (multi-)FASTA .fa/.mfa" ## [29] " -r query input files are raw one-sequence-per-line" ## [30] " -F k:<int>,i:<int> query input files are continuous FASTA where reads" ## [31] " are substrings (k-mers) extracted from a FASTA file <s>" ## [32] " and aligned at offsets 1, 1+i, 1+2i ... end of reference" ## [33] " -c <m1>, <m2>, <r> are sequences themselves, not files" ## [34] " -s/--skip <int> skip the first <int> reads/pairs in the input (none)" ## [35] " -u/--upto <int> stop after first <int> reads/pairs (no limit)" ## [36] " -5/--trim5 <int> trim <int> bases from 5'/left end of reads (0)" ## [37] " -3/--trim3 <int> trim <int> bases from 3'/right end of reads (0)" ## [38] " --trim-to [3:|5:]<int> trim reads exceeding <int> bases from either 3' or 5' end" ## [39] " If the read end is not specified then it defaults to 3 (0)" ## [40] " --phred33 qualities are Phred+33 (default)" ## [41] " --phred64 qualities are Phred+64" ## [42] " --int-quals qualities encoded as space-delimited integers" ## [43] "" ## [44] " Presets: Same as:" ## [45] " For --end-to-end:" ## [46] " --very-fast -D 5 -R 1 -N 0 -L 22 -i S,0,2.50" ## [47] " --fast -D 10 -R 2 -N 0 -L 22 -i S,0,2.50" ## [48] " --sensitive -D 15 -R 2 -N 0 -L 22 -i S,1,1.15 (default)" ## [49] " --very-sensitive -D 20 -R 3 -N 0 -L 20 -i S,1,0.50" ## [50] "" ## [51] " For --local:" ## [52] " --very-fast-local -D 5 -R 1 -N 0 -L 25 -i S,1,2.00" ## [53] " --fast-local -D 10 -R 2 -N 0 -L 22 -i S,1,1.75" ## [54] " --sensitive-local -D 15 -R 2 -N 0 -L 20 -i S,1,0.75 (default)" ## [55] " --very-sensitive-local -D 20 -R 3 -N 0 -L 20 -i S,1,0.50" ## [56] "" ## [57] " Alignment:" ## [58] " -N <int> max # mismatches in seed alignment; can be 0 or 1 (0)" ## [59] " -L <int> length of seed substrings; must be >3, <32 (22)" ## [60] " -i <func> interval between seed substrings w/r/t read len (S,1,1.15)" ## [61] " --n-ceil <func> func for max # non-A/C/G/Ts permitted in aln (L,0,0.15)" ## [62] " --dpad <int> include <int> extra ref chars on sides of DP table (15)" ## [63] " --gbar <int> disallow gaps within <int> nucs of read extremes (4)" ## [64] " --ignore-quals treat all quality values as 30 on Phred scale (off)" ## [65] " --nofw do not align forward (original) version of read (off)" ## [66] " --norc do not align reverse-complement version of read (off)" ## [67] " --no-1mm-upfront do not allow 1 mismatch alignments before attempting to" ## [68] " scan for the optimal seeded alignments" ## [69] " --end-to-end entire read must align; no clipping (on)" ## [70] " OR" ## [71] " --local local alignment; ends might be soft clipped (off)" ## [72] "" ## [73] " Scoring:" ## [74] " --ma <int> match bonus (0 for --end-to-end, 2 for --local) " ## [75] " --mp <int> max penalty for mismatch; lower qual = lower penalty (6)" ## [76] " --np <int> penalty for non-A/C/G/Ts in read/ref (1)" ## [77] " --rdg <int>,<int> read gap open, extend penalties (5,3)" ## [78] " --rfg <int>,<int> reference gap open, extend penalties (5,3)" ## [79] " --score-min <func> min acceptable alignment score w/r/t read length" ## [80] " (G,20,8 for local, L,-0.6,-0.6 for end-to-end)" ## [81] "" ## [82] " Reporting:" ## [83] " (default) look for multiple alignments, report best, with MAPQ" ## [84] " OR" ## [85] " -k <int> report up to <int> alns per read; MAPQ not meaningful" ## [86] " OR" ## [87] " -a/--all report all alignments; very slow, MAPQ not meaningful" ## [88] "" ## [89] " Effort:" ## [90] " -D <int> give up extending after <int> failed extends in a row (15)" ## [91] " -R <int> for reads w/ repetitive seeds, try <int> sets of seeds (2)" ## [92] "" ## [93] " Paired-end:" ## [94] " -I/--minins <int> minimum fragment length (0)" ## [95] " -X/--maxins <int> maximum fragment length (500)" ## [96] " --fr/--rf/--ff -1, -2 mates align fw/rev, rev/fw, fw/fw (--fr)" ## [97] " --no-mixed suppress unpaired alignments for paired reads" ## [98] " --no-discordant suppress discordant alignments for paired reads" ## [99] " --dovetail concordant when mates extend past each other" ## [100] " --no-contain not concordant when one mate alignment contains other" ## [101] " --no-overlap not concordant when mates overlap at all" ## [102] "" ## [103] " BAM:" ## [104] " --align-paired-reads" ## [105] " Bowtie2 will, by default, attempt to align unpaired BAM reads." ## [106] " Use this option to align paired-end reads instead." ## [107] " --preserve-tags Preserve tags from the original BAM record by" ## [108] " appending them to the end of the corresponding SAM output." ## [109] "" ## [110] " Output:" ## [111] " -t/--time print wall-clock time taken by search phases" ## [112] " --un <path> write unpaired reads that didn't align to <path>" ## [113] " --al <path> write unpaired reads that aligned at least once to <path>" ## [114] " --un-conc <path> write pairs that didn't align concordantly to <path>" ## [115] " --al-conc <path> write pairs that aligned concordantly at least once to <path>" ## [116] " (Note: for --un, --al, --un-conc, or --al-conc, add '-gz' to the option name, e.g." ## [117] " --un-gz <path>, to gzip compress output, or add '-bz2' to bzip2 compress output.)" ## [118] " --quiet print nothing to stderr except serious errors" ## [119] " --met-file <path> send metrics to file at <path> (off)" ## [120] " --met-stderr send metrics to stderr (off)" ## [121] " --met <int> report internal counters & metrics every <int> secs (1)" ## [122] " --no-unal suppress SAM records for unaligned reads" ## [123] " --no-head suppress header lines, i.e. lines starting with @" ## [124] " --no-sq suppress @SQ header lines" ## [125] " --rg-id <text> set read group id, reflected in @RG line and RG:Z: opt field" ## [126] " --rg <text> add <text> (\"lab:value\") to @RG line of SAM header." ## [127] " Note: @RG line only printed when --rg-id is set." ## [128] " --omit-sec-seq put '*' in SEQ and QUAL fields for secondary alignments." ## [129] " --sam-no-qname-trunc" ## [130] " Suppress standard behavior of truncating readname at first whitespace " ## [131] " at the expense of generating non-standard SAM." ## [132] " --xeq Use '='/'X', instead of 'M,' to specify matches/mismatches in SAM record." ## [133] " --soft-clipped-unmapped-tlen" ## [134] " Exclude soft-clipped bases when reporting TLEN" ## [135] " --sam-append-comment" ## [136] " Append FASTA/FASTQ comment to SAM record" ## [137] "" ## [138] " Performance:" ## [139] " -p/--threads <int> number of alignment threads to launch (1)" ## [140] " --reorder force SAM output order to match order of input reads" ## [141] " --mm use memory-mapped I/O for index; many 'bowtie's can share" ## [142] "" ## [143] " Other:" ## [144] " --qc-filter filter out reads that are bad according to QSEQ filter" ## [145] " --seed <int> seed for random number generator (0)" ## [146] " --non-deterministic" ## [147] " seed rand. gen. arbitrarily instead of using read attributes" ## [148] " --version print version information and quit" ## [149] " -h/--help print this usage message"

You can get version information by call:

bowtie2_version()

## arguments 'show.output.on.console', 'minimized' and 'invisible' are for Windows only

## [1] "/tmp/RtmpUxBONc/Rinstfc76268195eef/Rbowtie2/bowtie2-align-s version 2.4.4" ## [2] "64-bit" ## [3] "Built on nebbiolo2" ## [4] "Wed 1 May 23:00:35 UTC 2024" ## [5] "Compiler: gcc version 11.4.0 (Ubuntu 11.4.0-1ubuntu1~22.04) " ## [6] "Options: -O3 -msse2 -funroll-loops -g3 -std=c++11 -DPOPCNT_CAPABILITY -DNO_SPINLOCK -DWITH_QUEUELOCK=1"## [7] "Sizeof {int, long, long long, void*, size_t, off_t}: {4, 8, 8, 8, 8, 8}"