BLOOMFILTER.SH(1)

💖 bloomfilter.sh — BLOOMFILTER.SH(1) 💖

okay bestie, gather round, because this one is a filter and it's giving main character energy 🦋

---

✨ NAME ✨

bloomfilter.sh — filters reads that might be sharing a kmer with a reference. yes that's the whole vibe 💅

---

🌸 SYNOPSIS 🌸

bloomfilter.sh in=<input file> out=<nonmatches> outm=<matches>
ref=<reference>

---

💫 DESCRIPTION 💫

So what it does: it filters reads that potentially share a kmer with a reference. that's it, that's the job 🫶

And here's the tea — the more memory you give it, the higher the accuracy. lowkey a memory-hungry queen 👑

Now the important part, no cap: reads going to outu are guaranteed to not match the reference. but reads going to outm might may or may not match the reference. so like… outu is a firm no, outm is a maybe 🙈

---

🔥 EXAMPLES 🔥

bloomfilter.sh in=reads.fq outm=nonhuman.fq outm=human.fq k=31 minhits=3
ref=human.fa

and also, iconic detail: error correction and depth filtering can be done simultaneously. multitasking icon 💅

---

👑 OPTIONS 👑

🎀 File parameters:

• in=<file> — the primary input, or read 1 input if you've got pairs.
• in2=<file> — read 2 input, for when your reads live in two separate files.
• outm=<file> — (out) the primary matched read output.
• outm2=<file> — (out2) matched read 2 output, if your reads are in two files.
• outu=<file> — primary unmatched read output.
• outu2=<file> — unmatched read 2 output, again for the two-file girlies.
• ref=<file> — reference sequence file, or a comma-delimited list of them.
  • For depth-based filtering, set this to the same as the input. 🫡
• overwrite=t (ow) — set it to false and the program will straight up abort instead of overwriting a file you already have. protect your files bestie 😭

🧚 Hashing parameters:

• k=31 — kmer length.
• hashes=2 — number of hashes per kmer. higher generally reduces false positives, but you pay for it in speed. tradeoffs, always tradeoffs 💀
• minprob=0.5 — ignore reference kmers whose probability of being correct is below this. (this only affects fastq references, fyi.)
• memmult=1.0 — the fraction of free memory to use for the Bloom filter. 1.0 should generally work; if the program crashes with an out-of-memory error, set this lower. higher increases specificity. so basically: crank it, but not so hard it dies 🌈
• cells= — option to set the number of cells manually. by default this gets autoset to use all available memory. the only reason to set this is if you want deterministic output. periodt.
• seed=0 — this will change the hash function used. ✨

🦋 Reference-matching parameters:

• minhits=3 — consecutive kmer hits needed for a read to be considered matched.
  • higher reduces false positives at the expense of sensitivity.
• mincount=1 — minimum number of times a read kmer must occur in the reference to count as a match.
• requireboth=f — require both reads in a pair to match the ref before they go to outm.
  • by default, pairs go to outm if either one matches. so f is the chill setting, t is the strict one 💅

⭐ 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. don't be greedy bestie 🙈
• -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 🫶

Please contact Brian Bushnell at bbushnell@lbl.gov if you encounter any problems. he's literally the guy, hit him up if stuff breaks 😭

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

---

and that's a wrap!! this is bloomfilter.sh version 38.43, dated March 2019 — go forth and filter, you've got this, mwah 💖🌸✨