BBMAP.SH(1)

📦
version 39.20 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 BBMAP.SH(1) — bbmap.sh 💖

okay bestie, buckle UP, because bbmap.sh from the BBMAP.SH(1) manual is literally the fast and accurate splice-aware read aligner and we are going to get you fluent in it. this is part 1, so no, we are not done, keep scrolling energy 🫶

✨ NAME ✨

bbmap.sh — Fast and accurate splice-aware read aligner. that's it, that's the whole vibe. she aligns reads, she handles splices, she's fast, she's accurate. icon behavior 👑

🌸 SYNOPSIS 🌸

To index:

bbmap.sh ref=<reference fasta>

To map:

bbmap.sh in=<reads> out=<output sam>

To map without writing an index:

bbmap.sh ref=<reference fasta> in=<reads> out=<output sam> nodisk

🎀 OPTIONS 🎀

so <pink>in=stdin</pink> will accept reads from standard in, and <pink>out=stdout</pink> will write to standard out — but bestie, file extensions are STILL needed to specify the format of the input and output files, okay? like <purple>in=stdin.fa.gz</purple> will read gzipped fasta from standard in, and <purple>out=stdout.sam.gz</purple> will write gzipped sam. don't skip the extension, she needs it 💅

🧚 Indexing Parameters (required when building the index) 🧚

these are the ones you need when you're building the index, no cap:

  • nodisk=f — set to true to build the index in memory and write nothing to disk except output. lowkey a vibe if you don't want index files lying around.
  • ref=<file> — specify the reference sequence. only do this ONCE, when building the index (unless you're using <cyan>nodisk</cyan>). one and done, bestie.
  • build=1 — if multiple references are indexed in the same directory, each one needs a unique numeric ID (unless you're using <cyan>nodisk</cyan>). gotta keep them distinguishable, iykyk.
  • k=13 — kmer length, range <yellow>8-15</yellow>. longer is faster but uses more memory. shorter is more sensitive. the eternal tradeoff, she's giving balance ⚖️
    • if indexing and mapping are done in two steps, K should be specified each time. both times, don't forget.
  • path=<.> — specify the location to write the index, if you don't want it in the current working directory. send her somewhere else 🦋
  • usemodulo=f — throw away ~80% of kmers based on remainder modulo a number (reduces RAM by 50% and sensitivity slightly). should be enabled both when building the index AND when mapping. both times. both. 👀
  • rebuild=f — force a rebuild of the index (ref= should be set). out with the old, in with the new ✨

🌈 Input Parameters 🌈

  • build=1 — designate index to use. corresponds to the number specified when building the index.
  • in=<file> — primary reads input; required parameter. required required, like actually required 💀
  • in2=<file> — for paired reads in two files.
  • interleaved=auto — true forces paired/interleaved input; false forces single-ended mapping. if not specified, interleaved status will be autodetected from read names. she'll figure it out herself, main character energy.
  • fastareadlen=500 — break up FASTA reads longer than this. max is <yellow>500</yellow> for BBMap and <yellow>6000</yellow> for BBMapPacBio. only works for FASTA input (use <purple>maxlen</purple> for FASTQ input). the default for bbmap.sh is <yellow>500</yellow>, and for mapPacBio.sh is <yellow>6000</yellow>.
  • unpigz=f — spawn a pigz (parallel gzip) process for faster decompression than using Java. requires pigz to be installed. no pigz, no party 🐷
  • touppercase=t — (tuc) convert lowercase letters in reads to upper case (otherwise they will not match the reference). lowercase letters just will not match, fr fr.

🍓 Sampling Parameters 🍓

  • reads=-1 — set to a positive number N to only process the first N reads (or pairs), then quit. <yellow>-1</yellow> means use all reads. all of them. every last one.
  • samplerate=1 — set to a number from <yellow>0</yellow> to <yellow>1</yellow> to randomly select that fraction of reads for mapping. <yellow>1</yellow> uses all reads.
  • skipreads=0 — set to a number N to skip the first N reads (or pairs), then map the rest. bye to the first N, hello to the rest 👋

🔥 Mapping Parameters 🔥

  • fast=f — this flag is a macro which sets other parameters to run faster, at reduced sensitivity. bad for RNA-seq. noted. don't do it for RNA-seq.
  • slow=f — this flag is a macro which sets other parameters to run slower, at greater sensitivity. <cyan>vslow</cyan> is even slower. she can go slower. she can go even slower than that.
  • maxindel=16000 — don't look for indels longer than this. lower is faster.
    • set to <yellow>>=100k</yellow> for RNAseq with long introns like mammals. mammals are built different.
  • strictmaxindel=f — when enabled, do not allow indels longer than <cyan>maxindel</cyan>.
    • by default these are not sought, but may be found anyway. sneaky little indels 🙈
  • tipsearch=100 — look this far for read-end deletions with anchors shorter than K, using brute force. brute force, but make it fashion.
  • minid=0.76 — approximate minimum alignment identity to look for.
    • higher is faster and less sensitive.
  • minhits=1 — minimum number of seed hits required for candidate sites.
    • higher is faster.
  • local=f — set to true to use local, rather than global, alignments.
    • this will soft-clip ugly ends of poor alignments. giving those ends a little glow-up ✂️
  • perfectmode=f — allow only perfect mappings when set to true (very fast). perfectionism but productive.
  • semiperfectmode=f — allow only perfect and semiperfect (perfect except for N's in the reference) mappings. perfection, with exceptions, for N's only.
  • threads=auto — (t) set to number of threads desired. by default, uses all cores available. all of them. she's hungry.
  • ambiguous=best — (ambig) set behavior on ambiguously-mapped reads (with multiple top-scoring mapping locations).
    • best (use the first best site)
    • toss (consider unmapped)
    • random (select one top-scoring site randomly)
    • all (retain all top-scoring sites)
  • samestrandpairs=f — (ssp) specify whether paired reads should map to the same strand or opposite strands.
  • requirecorrectstrand=t — (rcs) forbid pairing of reads without correct strand orientation.
    • set to false for long-mate-pair libraries.
  • killbadpairs=f — (kbp) if a read pair is mapped with an inappropriate insert size or orientation, the read with the lower mapping quality is marked unmapped. it's giving consequences.
  • pairedonly=f — (po) treat unpaired reads as unmapped. thus they will be sent to <cyan>outu</cyan> but not <cyan>outm</cyan>.
  • rcomp=f — reverse complement both reads prior to mapping (for LMP outward-facing libraries).
  • rcompmate=f — reverse complement read2 prior to mapping.
  • pairlen=32000 — set max allowed distance between paired reads.
    • (insert size)=(pairlen)+(read1 length)+(read2 length). do the math, bestie 🧮
  • rescuedist=1200 — don't try to rescue paired reads if avg. insert size greater than this. lower is faster.
  • rescuemismatches=32 — maximum mismatches allowed in a rescued read. lower is faster.
  • averagepairdist=100 — (apd) initial average distance between paired reads.
    • varies dynamically; does not need to be specified.
  • deterministic=f — run in deterministic mode. in this case it is good to set <cyan>averagepairdist</cyan>. BBMap is deterministic without this flag if using single-ended reads, or run singlethreaded.
  • bandwidthratio=0 — (bwr) if above zero, restrict alignment band to this fraction of read length. faster but less accurate.
  • bandwidth=0 — (bw) set the bandwidth directly. fraction of read length. faster but less accurate.
  • usejni=f — (jni) do alignments faster, in C code. requires compiling the C code; details are in /jni/README.txt.
  • maxsites2=800 — don't analyze (or print) more than this many alignments per read.
  • ignorefrequentkmers=t — (ifk) discard low-information kmers that occur often.
  • excludefraction=0.03 — (ef) fraction of kmers to ignore. for example, <yellow>0.03</yellow> will ignore the most common 3% of kmers.
  • greedy=t — use a greedy algorithm to discard the least-useful kmers on a per-read basis. greedy in a cute way 💅
  • kfilter=0 — if positive, potential mapping sites must have at least this many consecutive exact matches.

🦋 Quality and Trimming Parameters 🦋

  • qin=auto — set to <yellow>33</yellow> or <yellow>64</yellow> to specify input quality value ASCII offset. <yellow>33</yellow> is Sanger, <yellow>64</yellow> is old Solexa.
  • qout=auto — set to <yellow>33</yellow> or <yellow>64</yellow> to specify output quality value ASCII offset (only if output format is fastq).
  • qtrim=f — quality-trim ends before mapping. options are: <yellow>'f'</yellow> (false), <yellow>'l'</yellow> (left), <yellow>'r'</yellow> (right), and <yellow>'lr'</yellow> (both).
  • untrim=f — undo trimming after mapping. untrimmed bases will be soft-clipped in cigar strings.
  • trimq=6 — trim regions with average quality below this (phred algorithm).
  • mintrimlength=60 — (mintl) don't trim reads to be shorter than this. she has boundaries.
  • fakefastaquality=-1 — (ffq) set to a positive number <yellow>1-50</yellow> to generate fake quality strings for fasta input reads. fake it till you make it ✨
  • ignorebadquality=f — (ibq) keep going, rather than crashing, if a read has out-of-range quality values. we do not crash in this house.
  • usequality=t — use quality scores when determining which read kmers to use as seeds.
  • minaveragequality=0 — (maq) do not map reads with average quality below this.
  • maqb=0 — if positive, calculate maq from this many initial bases.

👑 Output Parameters 👑

  • out=<file> — write all reads to this file.
  • outu=<file> — write only unmapped reads to this file. does not include unmapped paired reads with a mapped mate.
  • outm=<file> — write only mapped reads to this file. includes unmapped paired reads with a mapped mate.
  • mappedonly=f — if true, treats <cyan>out</cyan> like <cyan>outm</cyan>.
  • bamscript=<file> — (bs) write a shell script to <file> that will turn the sam output into a sorted, indexed bam file. she writes the script for you, you're welcome.
  • ordered=f — set to true to output reads in same order as input. slower and uses more memory.
  • overwrite=f — (ow) allow process to overwrite existing files. only if you say so.
  • secondary=f — print secondary alignments.
  • sssr=0.95 — (secondarysitescoreratio) print only secondary alignments with score of at least this fraction of primary.
  • ssao=f — (secondarysiteasambiguousonly) only print secondary alignments for ambiguously-mapped reads.
  • maxsites=5 — maximum number of total alignments to print per read. only relevant when <cyan>secondary=t</cyan>.
  • quickmatch=f — generate cigar strings more quickly.
  • trimreaddescriptions=f — (trd) truncate read and ref names at the first whitespace, assuming that the remainder is a comment or description.
  • ziplevel=2 — (zl) compression level for zip or gzip output.
  • pigz=f — spawn a pigz (parallel gzip) process for faster compression than Java. requires pigz to be installed.
  • machineout=f — set to true to output statistics in machine-friendly <yellow>'key=value'</yellow> format.
  • printunmappedcount=f — print the total number of unmapped reads and bases.
    • if input is paired, the number will be of pairs for which both reads are unmapped.
  • showprogress=0 — if positive, print a <yellow>'.'</yellow> every X reads. little dots of encouragement 🎀
  • showprogress2=0 — if positive, print the number of seconds since the last progress update (instead of a <yellow>'.'</yellow>).
  • renamebyinsert=f — renames reads based on their mapped insert size.

and that's part 1, bestie — there's more coming, so don't go anywhere 💜

🌸 Bloom-Filtering Parameters (bloomfilter.sh is the standalone version) 🌸

  • bloom=f — turn on a Bloom filter so reads that share zero kmers with the reference get yeeted before they even get a chance. It eats more memory, but if most of your reads aren't matching anything, this makes mapping go so much faster. Bestie it's a whole timesaver 💅
  • bloomhashes=2 — how many hash functions you want.
  • bloomminhits=3 — how many hits in a row count as "okay yeah this one matched".
  • bloomk=31 — the kmer length used by the Bloom filter.
  • bloomserial=t — use the serialized Bloom filter because loading it is way speedier, if you happen to have one. If you don't, it'll just make one and write it out for you. 🫶

✨ Post-Filtering Parameters ✨

  • idfilter=0 — totally separate from minid; this sets the exact minimum identity an alignment needs before it's allowed to be printed. Range is 0 to 1.
  • subfilter=-1 — ban any alignment rocking more than this many substitutions.
  • insfilter=-1 — ban any alignment with more than this many insertions.
  • delfilter=-1 — ban any alignment with more than this many deletions.
  • indelfilter=-1 — ban any alignment with more than this many indels.
  • editfilter=-1 — ban any alignment with more than this many edits.
  • inslenfilter=-1 — ban any alignment whose insertion is longer than this.
  • dellenfilter=-1 — ban any alignment whose deletion is longer than this.
  • nfilter=-1 — ban any alignment with more than this many ns. And bestie, that count includes nocall, noref, and anything hanging off the ends of scaffolds. 🙈

💖 Sam flags and settings 💖

  • noheader=f — stop generating header lines.
  • sam=1.4 — set it to 1.4 and you get Sam version 1.4 cigar strings, complete with = and X. Set it to 1.3 if you want plain old M instead.
  • saa=t (secondaryalignmentasterisks) — use asterisks instead of bases for sam secondary alignments. Slay.
  • cigar=t — set it to 'f' to skip making cigar strings entirely (which, yes, is faster).
  • keepnames=f — keep the original names of paired reads instead of forcing both reads to share one name.
  • intronlen=999999999 — drop this to something small like 10 and 'D' becomes 'N' in cigar strings for any deletion at least that long.
  • rgid= — set the readgroup ID. Every other readgroup field works the same way, just with the flag rgXX=. And if you set a readgroup flag to the word 'filename' — like rgid=filename — then the input file name gets used instead. 🎀
  • mdtag=f — write MD tags.
  • nhtag=f — write NH tags.
  • xmtag=f — write XM tags (heads up: this may only work correctly with ambig=all).
  • amtag=f — write AM tags.
  • nmtag=f — write NM tags.
  • xstag=f — set it to 'xs=fs', 'xs=ss', or 'xs=us' to write XS tags for RNAseq using firststrand, secondstrand, or unstranded libraries. Cufflinks literally needs this. And JGI mainly uses 'firststrand'.
  • stoptag=f — write a tag showing where the read stops, prefixed with YS:i:.
  • lengthtag=f — write a tag showing (query,ref) alignment lengths, prefixed with YL:Z:.
  • idtag=f — write a tag showing percent identity, prefixed with YI:f:.
  • inserttag=f — write a tag showing insert size, prefixed with X8:Z:.
  • scoretag=f — write a tag showing BBMap's raw score, prefixed with YR:i:.
  • timetag=f — write a tag showing how long this read took to map, prefixed with X0:i:.
  • boundstag=f — write a tag showing whether either read in the pair runs off the end of the reference, prefixed with XB:Z:.
  • notags=f — turn off all the optional tags at once. One flag, no tags, iconic.

🦋 Histogram and statistics output parameters 🦋

  • scafstats=<file> — stats on how many reads mapped to which scaffold.
  • refstats=<file> — stats on how many reads mapped to which reference file; this one's only for BBSplit.
  • sortscafs=t — sort scaffolds or references by read count.
  • bhist=<file> — base composition histogram, by position.
  • qhist=<file> — quality histogram, by position.
  • aqhist=<file> — histogram of average read quality.
  • bqhist=<file> — a quality histogram designed for box plots.
  • lhist=<file> — read length histogram.
  • ihist=<file> — write a histogram of insert sizes (for paired reads).
  • ehist=<file> — errors-per-read histogram.
  • qahist=<file> — quality accuracy histogram of error rates vs quality score.
  • indelhist=<file> — indel length histogram.
  • mhist=<file> — histogram of match, sub, del, and ins rates by read location.
  • gchist=<file> — read GC content histogram.
  • gcbins=100 — how many gchist bins. Set it to 'auto' to use read length.
  • gcpairs=t — use the average GC of paired reads.
  • idhist=<file> — histogram of read count vs percent identity.
  • idbins=100 — how many idhist bins. Set it to 'auto' to use read length.
  • statsfile=stderr — mapping statistics get printed right here.

👑 Coverage output parameters (these may reduce speed and use more RAM) 👑

Fr fr, these ones can slow you down and gobble up extra RAM, so only turn on the ones you actually want. 💀
  • covstats=<file> — per-scaffold coverage info.
  • rpkm=<file> — per-scaffold RPKM/FPKM counts.
  • covhist=<file> — histogram of the number of occurrences of each depth level.
  • basecov=<file> — coverage per base location.
  • bincov=<file> — print binned coverage per location (one line per X bases).
  • covbinsize=1000 — set the binsize for binned coverage output.
  • nzo=t — only print scaffolds with nonzero coverage.
  • twocolumn=f — change to true to print only ID and Avg_fold instead of all 6 columns to the 'out=' file.
  • 32bit=f — set to true if you need per-base coverage over 64k.
  • strandedcov=f — track coverage for plus and minus strand separately.
  • startcov=f — only track start positions of reads.
  • secondarycov=t — include coverage of secondary alignments.
  • physcov=f — calculate physical coverage for paired reads. This includes the unsequenced bases.
  • delcoverage=t (delcov) — count bases covered by deletions as covered. True is faster than false, bestie.
  • covk=0 — if positive, calculate kmer coverage statistics.

⭐ Java Parameters ⭐

  • -Xmx — this sets Java's memory usage and overrides autodetection. -Xmx20g gives you 20 gigs of RAM, -Xmx800m gives you 800 megs. The max is typically 85% of physical memory. The human genome needs around 24g, or 12g if you use the 'usemodulo' flag. And the index uses roughly 6 bytes per reference base. 🧚
  • -eoom — this flag makes the process exit if an out-of-memory exception happens. Requires Java 8u92+.
  • -da — disable assertions.

🌈 SEE ALSO 🌈

Please read bbmap/docs/guides/BBMapGuide.txt for more information.

💜 AUTHOR 💜

Written by Brian Bushnell, from Dec. 2010 - present

Please contact Brian Bushnell at bbushnell@lbl.gov if you encounter any problems, or post at: http://seqanswers.com/forums/showthread.php?t=41057

This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program.

And that's a wrap on bbmap.sh, bestie — this is version 39.11 from September 2022, aka the BBMAP.SH(1) era. Go map some reads and slay. 💅✨

📦 where this page comes from