BBNORM.SH(1)

💖 BBNORM.SH — bestie edition 💖

okay so this is a page from the User Commands manual, and honestly? it's giving ✨kmer magic✨. welcome to bbnorm.sh, bestie, let's get into it 🫶

---

🌸 NAME 🌸

bbnorm.sh — the kmer-based error-correction and normalization tool 💅

---

✨ SYNOPSIS ✨

bbnorm.sh in=<input> out=<reads to keep> outt=<reads to toss>
hist=<histogram output>

---

🦋 DESCRIPTION 🦋

So what does it even do? It normalizes read depth based on kmer counts, periodt. It can also error-correct, bin reads by kmer depth, and generate a kmer depth histogram — like, it does a lot 👑

BUT. Real talk. Tadpole has superior error-correction to BBNorm 😭 so if you're here specifically for error correction, know that.

Please read bbmap/docs/guides/BBNormGuide.txt for more information — it's lowkey required reading, no cap.

---

🎀 OPTIONS 🎀

💜 Input parameters

• in=null — the primary input, your main character. Use in2 for paired reads in a second file.
• in2=null — second input file, for when your paired reads live in two separate files.
• extra=null — extra files that get used for input (building the hash table) but not for output. iykyk.
• fastareadlen=2^31 — breaks up FASTA reads longer than this. super useful when you're processing scaffolded genomes 🧬
• tablereads=-1 — use at most this many reads when building the hashtable (-1 means all of them, go wild).
• kmersample=1 — process every *n*th kmer and skip the rest.
• readsample=1 — process every *n*th read and skip the rest.
• interleaved=auto — may be set to true or false to force the input read file to override autodetection of the input file as paired interleaved.
• qin=auto — ASCII offset for input quality. May be 33 (Sanger), 64 (Illumina), or auto.

💖 Output parameters

• out=<file> — file for normalized or corrected reads. Use out2 for paired reads in a second file.
• outt=<file> — also known as outtoss. File for reads that were excluded from the primary output. bye bestie 👋
• reads=-1 — only process this number of reads, then quit (-1 means all).
• sampleoutput=t — use sampling on output as well as input (not used if sample rates are 1).
• keepall=f — set to true to keep all reads (like, if you just want error correction and nothing else).
• zerobin=f — set to true if you want kmers with a count of 0 to go in the 0 bin instead of the 1 bin in histograms.

Default is false, to prevent confusion about how there can be 0-count kmers. The reason is that based on the minq and minprob settings, some kmers may be excluded from the bloom filter. (mystery solved 🔍)

• tmpdir= — this will specify a directory for temp files (only needed for multipass runs). If null, they will be written to the output directory.
• usetempdir=t — allows enabling/disabling of temporary directory; if disabled, temp files will be written to the output directory.
• qout=auto — ASCII offset for output quality. May be 33 (Sanger), 64 (Illumina), or auto (same as input).
• rename=f — rename reads based on their kmer depth.

🔥 Hashing parameters

• k=31 — kmer length (values under 32 are most efficient, but arbitrarily high values are supported).
• bits=32 — bits per cell in bloom filter; must be 2, 4, 8, 16, or 32. Maximum kmer depth recorded is 2^cbits. Automatically reduced to 16 in 2-pass.

Large values decrease accuracy for a fixed amount of memory, so use the lowest number you can that will still capture highest-depth kmers. fr fr.

• hashes=3 — number of times each kmer is hashed and stored. Higher is slower.

Higher is MORE accurate if there is enough memory, and LESS accurate if there is not enough memory. the duality of man 😭

• prefilter=f — true is slower, but generally more accurate; filters out low-depth kmers from the main hashtable. The prefilter is more memory-efficient because it uses 2-bit cells.
• prehashes=2 — number of hashes for prefilter.
• prefilterbits=2 — also known as pbits. Bits per cell in prefilter.
• prefiltersize=0.35 — fraction of memory to allocate to prefilter.
• buildpasses=1 — more passes can sometimes increase accuracy by iteratively removing low-depth kmers.
• minq=6 — ignore kmers containing bases with quality below this.
• minprob=0.5 — ignore kmers with overall probability of correctness below this.
• threads=auto — also known as t. Spawn exactly X hashing threads (default is number of logical processors). Total active threads may exceed X due to I/O threads.
• rdk=t — also known as removeduplicatekmers. When true, a kmer's count will only be incremented once per read pair, even if that kmer occurs more than once.

💅 Normalization parameters

• fixspikes=f — also known as fs. Do a slower, high-precision bloom filter lookup of kmers that appear to have an abnormally high depth due to collisions.
• target=100 — also known as tgt. Target normalization depth. NOTE: All depth parameters control kmer depth, not read depth. 👑

For kmer depth Dk, read depth Dr, read length R, and kmer size K:

Dr=Dk*(R/(R-K+1))

• maxdepth=-1 — also known as max. Reads will not be downsampled when below this depth, even if they are above the target depth.
• mindepth=5 — also known as min. Kmers with depth below this number will not be included when calculating the depth of a read.
• minkmers=15 — also known as mgkpr. Reads must have at least this many kmers over min depth to be retained. Aka mingoodkmersperread.
• percentile=54.0 — also known as dp. Read depth is by default inferred from the 54th percentile of kmer depth, but this may be changed to any number 1-100.
• uselowerdepth=t — also known as uld. For pairs, use the depth of the lower read as the depth proxy.
• deterministic=t — also known as dr. Generate random numbers deterministically to ensure identical output between multiple runs. May decrease speed with a huge number of threads.
• passes=2 — also known as p. 1 pass is the basic mode. 2 passes (default) allows greater accuracy, error detection, better contol of output depth. (yes, "contol" — that's the original spelling, we keep it verbatim bestie 💀)

🍓 Error detection parameters

• hdp=90.0 — also known as highdepthpercentile. Position in sorted kmer depth array used as proxy of a read's high kmer depth.
• ldp=25.0 — also known as lowdepthpercentile. Position in sorted kmer depth array used as proxy of a read's low kmer depth.
• tossbadreads=f — also known as tbr. Throw away reads detected as containing errors.
• requirebothbad=f — also known as rbb. Only toss bad pairs if both reads are bad.
• errordetectratio=125 — also known as edr. Reads with a ratio of at least this much between their high and low depth kmers will be classified as error reads.
• highthresh=12 — also known as ht. Threshold for high kmer. A high kmer at this or above are considered non-error.
• lowthresh=3 — also known as lt. Threshold for low kmer. Kmers at this and below are always considered errors.

🌈 Error correction parameters

• ecc=f — set to true to correct errors. NOTE: Tadpole is now preferred for ecc as it does a better job. just saying 👀
• ecclimit=3 — correct up to this many errors per read. If more are detected, the read will remain unchanged.
• errorcorrectratio=140 — also known as ecr. Adjacent kmers with a depth ratio of at least this much between will be classified as an error.
• echighthresh=22 — also known as echt. Threshold for high kmer. A kmer at this or above may be considered non-error.
• eclowthresh=2 — also known as eclt. Threshold for low kmer. Kmers at this and below are considered errors.
• eccmaxqual=127 — do not correct bases with quality above this value.
• aec=f — also known as aggressiveErrorCorrection. Sets more aggressive values of ecr=100, ecclimit=7, echt=16, eclt=3.
• cec=f — also known as conservativeErrorCorrection. Sets more conservative values of ecr=180, ecclimit=2, echt=30, eclt=1, sl=4, pl=4.
• meo=f — also known as markErrorsOnly. Marks errors by reducing quality value of suspected errors; does not correct anything.
• mue=t — also known as markUncorrectableErrors. Marks errors only on uncorrectable reads; requires ecc=t.
• overlap=f — also known as ecco. Error correct by read overlap.

🧚 Depth binning parameters

• lowbindepth=10 — also known as lbd. Cutoff for low depth bin.
• highbindepth=80 — also known as hbd. Cutoff for high depth bin.
• outlow=<file> — pairs in which both reads have a median below lbd go into this file.
• outhigh=<file> — pairs in which both reads have a median above hbd go into this file.
• outmid=<file> — all other pairs go into this file.

⭐ Histogram parameters

• hist=<file> — specify a file to write the input kmer depth histogram.
• histout=<file> — specify a file to write the output kmer depth histogram.
• histcol=3 — also known as histogramcolumns. Number of histogram columns, 2 or 3.
• pzc=f — also known as printzerocoverage. Print lines in the histogram with zero coverage.
• histlen=1048576 — max kmer depth displayed in histogram. Also affects statistics displayed, but does not affect normalization.

👑 Peak calling parameters

• peaks=<file> — write the peaks to this file. Default is stdout.
• minHeight=2 — also known as h. Ignore peaks shorter than this.
• minVolume=5 — also known as v. Ignore peaks with less area than this.
• minWidth=3 — also known as w. Ignore peaks narrower than this.
• minPeak=2 — also known as minp. Ignore peaks with an X-value below this.
• maxPeak=BIG — also known as maxp. Ignore peaks with an X-value above this.
• maxPeakCount=8 — also known as maxpc. Print up to this many peaks (prioritizing height).

☕ Java Parameters:

• -Xmx — this will set Java's memory usage, overriding autodetection.

-Xmx20g will specify 20 gigs of RAM, and -Xmx200m will specify 200 megs. The max is typically 85% of physical memory.

• -eoom — this flag will cause the process to exit if an out-of-memory exception occurs. Requires Java 8u92+.
• -da — disable assertions.

---

💌 AUTHOR 💌

Written by Brian Bushnell (Last modified October 19, 2017) 🫶

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 the whole page, bestie 💖 this was bbnorm.sh version 38.43, from April 2019 — slay, periodt, go normalize something ✨🌸🦋