BAITFILTER-V1.0.6(1)

✨ NAME ✨

Okay bestie, this is the manual for BAITFILTER-V1.0.6(1) 🎀, a User Commands page. The tool is BaitFilter-v1.0.6, and this page is its manual 💖

---

✨ DESCRIPTION ✨

Welcome to Bait-Filter, version 1.0.6! 🦋

💅 USAGE

./BaitFilter-v1.0.6
       -i <string> [-o <string>] [-c <string>] [-m <string>]
       [--blast-second-hit-evalue <floating point number>]
       [--blast-first-hit-evalue <floating point number>]
       [--blast-min-hit-coverage-of-baits-in-tiling-stack <floating
       point number>] [--ref-blast-db <string>]
       [--blast-extra-commandline <string>] [--blast-evalue-cutoff
       <floating point number>] [-B <string>] [-t <positive integer>]
       [--ID-prefix <string>] [-S] [--verbosity <unsigned integer>] [-b
       <string>] [--] [--version] [-h]

🌸 Where

• -i <string>, --input-bait-file-name <string> (required) — This is the input bait locus file you feed in, the one that came out of the BaitFisher program or out of an earlier BaitFilter run ✨
• -o <string>, --output-bait-file-name <string> — The name for your output bait file. Every mode except conversion spits out files in the BaitFisher format 🍓
• -c <string>, --convert <string> — This is how you get the final file that a bait producing company will accept for upload 💅. In this mode, BaitFilter reads your input bait file and, instead of filtering, builds a custom bait file ready to upload. To avoid confusion, you can't filter and convert in the same run. If you want both, call the program twice: first to filter, then to convert. The conversion parameter that's allowed right now is "four-column-upload".

New output formats can be added on request. Contact the author, Christoph Mayer, at Mayer Christoph <c.mayer.zfmk@uni-bonn.de> 💌

• -m <string>, --mode <string> — Besides the input file, this is the most important option 👑. It picks which filter mode BaitFilter uses. (Check the user manual for more details!)
  • "ab" — Keep only the best bait locus for each alignment file, using the optimality criterion to minimize the total number of required baits.
  • "as" — Keep only the best bait locus for each alignment file, using the optimality criterion to maximize the number of sequences the result is based on.
  • "fb" — Keep only the best bait locus for each feature (e.g. CDS), using the optimality criterion to minimize the total number of required baits. Only applicable if alignment cutting has been used in BaitFisher.
  • "fs" — Keep only the best bait locus for each feature (e.g. CDS), using the optimality criterion to maximize the number of sequences the result is based on. Only applicable if alignment cutting has been used in BaitFisher.
  • "blast-a" — Remove all bait regions of all ALIGNMENTs where one or more baits have at least two good hits to a reference genome. (Not recommended.) 🙈
  • "blast-f" — Remove all bait regions of all FEATUREs where one or more baits have at least two good hits to a reference genome. (Not recommended.) 🙈
  • "blast-l" — Remove only the bait REGIONs that contain a bait with multiple good hits to a reference genome. (Recommended over blast-f and blast-a 🔥)
  • "blast-c" — Run a coverage filter without searching for multiple hits. This one requires the --blast-min-hit-coverage-of-baits-in-tiling-stack option to be specified.
  • "thin-b" — Thin out a bait file to every Nth bait region, by finding the start position that minimizes the number of baits.
  • "thin-s" — Thin out a bait file to every Nth bait region, by finding the start position that maximizes the number of sequences.
  • "thin-b-old" — Similar to thin-b, but treats all loci as if they come from one alignment file. Identical to behaviour of thin-b in version 1.0.5 or earlier.
  • "thin-s-old" — Similar to thin-s, but treats all loci as if they come from one alignment file. Identical to behaviour of thin-b in version 1.0.5 or earlier.
• --blast-second-hit-evalue <floating point number> — This is the maximum E-value for the second or second best hit 🧐. A bait counts as binding ambiguously if we have at least two good hits. So this is the E-value threshold for that second best hit, aimed at different loci of the genome. Yep, it's the E-value threshold for the second best hit, twice on purpose 💜. Default: 0.000001
• --blast-first-hit-evalue <floating point number> — This is the maximum E-value for the first or best hit of the bait against the genome. A bait is considered ambiguous if it has at least two good hits to different loci of the genome. This option sets the E-value threshold for the first/best hit. Default: 0.000001
• --blast-min-hit-coverage-of-baits-in-tiling-stack <floating point number> — Pair this with the modes "blast-a", "blast-f", "blast-l", or "blast-c" (the -m option) 🌈. In all of these, every bait gets blasted against a reference genome. This option sets a minimum query hit coverage that at least one bait has to hit in each tiling stack (the column in the tiling design). If nobody in the stack makes the cut, the bait region gets tossed. If you don't specify it, no hit coverage is checked.

Coverage for each bait is found by dividing the length of its best hit against the specified genome by the length of the bait. Then the highest coverage in each bait stack of the tiling design is kept.

If you use this together with another filter, the order matters for the final result! For the mode options "blast-a", "blast-f", and "blast-l", hit coverage is checked after filtering for baits with multiple good hits to the reference genome.

• --ref-blast-db <string> — This is the base name of a blast database file, and it gets passed along to the blast command. It's also the name of the fasta file for your reference genome 🧬.

IMPORTANT: Run the makeblastdb program before you start Bait-Filter! makeblastdb takes the fasta file and creates database files out of it. This option can't be used together with the --blast-result-file option.

• --blast-extra-commandline <string> — Want to pass extra command line parameters to the blast program? This is your option 🚀. For example, you can use it to set how many threads blast uses. Example: --blast-extra-commandline "-num_threads 20" sets the number of threads to 20 🧵.
• --blast-evalue-cutoff <floating point number> — When you run a blast search, you can set a maximum E-value to pass to the blast program. Hits with a higher E-value don't get reported. BaitFilter always sends one of these E-values to blast. By default, that value is twice the --blast-second-hit-evalue 🎯.

If a coverage filter is requested, the default becomes 0.001 whenever twice the --blast-second-hit-evalue is smaller than 0.001. This should make sure every hit needed for the blast and/or coverage filter gets found ✨. If you want a different E-value threshold, set it with this option.

With version 1.0.6, the value is automatically bumped up so it's larger than or equal to 0.001 whenever the coverage filter is used. This makes this option unnecessary in most cases 💅.

• -B <string>, --blast-executable <string> — The name of the blast executable, or its path plus name 🛠️. Default: blastn. Minimum blast version number: Blast+ 2.2.x. Default: blastn. This can't be used together with the --blast-result-file option.
• -t <positive integer>, --thinning-step-width <positive integer> — Thin out the bait file by keeping only every Nth bait region 🦋. The integer you pass in is the step width N. If thin-b (thin-b-old) or thin-s (thin-s-old) mode is active, this option is required. Otherwise, you're not allowed to set it at all.
• --ID-prefix <string> — When converting to the four-column-upload format, every converted file needs a unique ProbeID prefix, because ProbeIDs can't be identical even across multiple files 🫶. With this option, you give every probe ID in the four-column-upload file that BaitFilter makes a prefix string.
• -S, --stats — This computes bait file characteristics for the input file and reports them 📊. It gets used automatically for every mode set with -m or for the conversion mode set with -c. The whole point of -S is to get stats without having to filter or convert the input file. In particular, -S mode doesn't need an output file specified.

This option has no effect when combined with the -m or -c modes.

• --verbosity <unsigned integer> — This controls how much info Bait-Filter chats about on the console while it runs 🗣️.
  • 0: Only the welcome message and essential error messages that make the program exit.
  • 1: Also report warnings.
  • 2: Also report progress.
  • 3: Report more detailed progress.
  • >10: Debug output.
  • Maximum 10000: Write all possible diagnostic output 🔍.

A value of 2 is required if you want startup parameters reported 🌷.

• -b <string>, --blast-result-file <string> — (description continues in the next part) 🎀

bestie, a blast search of every bait against a reference genome can take ages 🐢 and if you wanna compare different filtering settings, like different coverage thresholds, you'd have to redo the whole blast every single time 💀. This option skips the blast and uses whatever blast result file you point it at 🦋. But this one is sooo not a casual option ⚠️. Nothing (so far) checks that the blast result file actually matches your bait file, so you have to be sure 🫣.

Also, if a BaitFilter run did a blast search, it does not delete the blast result file when it's done. The file called blast_result.txt just stays in the working directory 📁. You can move it or rename it, and then feed it back in with this option for later runs ✨. If you have the slightest doubt about whether it's the right blast result file, don't use this option at all, periodt 🙅‍♀️.

⚠️ Caution, bestie! This option is only allowed in modes that would normally do a blast search. It also cannot be combined with blast-executable, blast-evalue-cutoff, blast-extra-commandline, or ref-blast-db, since those are blast-only options 💀.

• --, --ignore_rest — Ignores the rest of the labeled arguments that come after this flag 🙈.
• --version — Shows the version info and then bounces 👋.
• -h, --help — Shows the usage info and then bounces 👋.

---

The Bait-Filter program was made to post process the output of the BaitFisher program so you can pick the right bait regions and build your final bait set 🎀. BaitFilter has several filtering and conversion modes. If you need multiple filtering steps plus a final conversion, you start BaitFilter multiple times and feed the output of each run into the next step 🔁.

BaitFisher designs baits for every locus where a full bait region is possible. A bait region can start at any nucleotide as long as enough sequence remains after it 🧬. That output is huge, so BaitFilter's job is to find the optimal locus, or loci, for each feature, gene, or alignment 💅. Before picking the locus with the fewest baits or the biggest sequence coverage, you might wanna figure out which baits are expected to bind specifically in a given reference genome 🔍. That's done with a Blast search of the baits against a genome. Baits that are highly similar to at least two loci of the genome can be found, and their bait regions removed 🗑️. The blast result can also be used to set a minimum hit coverage of the baits in a bait region against the reference genome 📏. After the inferior loci are removed, the optimal bait region starting locus (start coordinate) can be picked with different criteria in a later BaitFilter run 👑.

As input, BaitFilter needs either a bait file made by BaitFisher or a BaitFile made by an earlier BaitFilter filtering run 📂. You give this bait file with the -i command line parameter (see below). You also have to name an output file with -o and pick a filter mode with -m 🌈.

To convert a file into the final, uploadable output format, check out the -c option below 🚀.

To get bait file statistics for an input file, check out the -S option below 📊.

Here are the different filter modes BaitFilter gives you 💖:

• 1a) Keep only the best bait locus per alignment file. Criterion: minimize the number of required baits 🎯.
• 1b) Keep only the best bait locus per alignment file. Criterion: maximize the number of sequences ✨.
• 2a) Keep only the best bait locus per feature (features have to be selected in BaitFisher first). Criterion: minimize the number of required baits 🎯.
• 2b) Keep only the best bait locus per feature (features have to be selected in BaitFisher first). Criterion: maximize the number of sequences ✨.
• 3) Use a blast search of the bait sequences against a reference genome to detect putative non-unique target loci. Non-unique target sites will have multiple good hits against the reference genome 👯. You can also set a minimum coverage for the best blast hit of each bait sequence against the genome. Heads up: all blast modes need extra command line parameters!! 🚨 These modes remove bait regions where multiple good blast hits were found, or where the baits have insufficiently long hits 🗑️. There are a few versions:
  • 3a) If a single bait is not unique, remove all bait regions from the current gene 🧹.
  • 3b) If a single bait is not unique, remove all bait regions from the current feature (if applicable) 🧹.
  • 3c) If a single bait is not unique, remove only the bait region that contains this bait 🎀.
• 4) Thin out the given bait file: keep only every Nth bait region, where N has to be set by you 🦋. There are two submodes:
  • 4a) Thin out bait regions by keeping only every Nth bait region in a bait file. The starting offset is chosen so the number of required baits is minimized 🎯.
  • 4b) Thin out bait regions by keeping only every Nth bait region in a bait file. The starting offset is chosen so the number of sequences the result is based on is maximized ✨.

Welcome to Bait-Filter, version 1.0.6.

./BaitFilter-v1.0.6  version: 1.0.6

✨ SEE ALSO ✨

The full documentation for BaitFilter-v1.0.6 is maintained as a Texinfo manual 📖. If the info and BaitFilter-v1.0.6 programs are properly installed at your site, run this command to get the complete manual:

info BaitFilter-v1.0.6

---

That's the whole page, bestie 🫶 BaitFilter v1.0.6 from January 2022, slay forever 💅🌸