CoveringSet

Input Parameters

in=<file>

Input FASTA of pool sequences (e.g. all tRNAs). Required unless families= is given.

out=<file>

Output file. Required. In nucleotide mode, and in single-pool amino mode (alphabet= set without families=), this is a FASTA of selected kmers with headers kmer_1, kmer_2, and so on. With families=, it is the covering-set TSV described under families= below.

extra=<file>

Optional additional sequences to weight the pool, typically consensus models. Added copies= times. Nucleotide mode only; protein modes use consensus= instead.

copies=10

Number of copies of extra sequences to add to the pool (nucleotide mode). When consensus= is given in family mode, this is the number of copies of each family's consensus added to its pool, unless consensuscopies= sets per-family counts.

rcomp=f

Canonicalize kmers: build the forward kmer and its reverse complement in the same rolling pass and count, select, and match only the canonical (max) form, so a motif and its reverse complement are treated as one kmer instead of two. Nucleotide mode only; rcomp=t with an amino alphabet is rejected.

Alphabet Parameters

Protein mode is enabled by setting alphabet= to anything other than nt. The default is nucleotide mode.

alphabet=nt

Default. Nucleotide mode with 2-bit encoding. rcomp= is allowed.

alphabet=amino

The 20 standard amino acids, one class per residue, 5 bits per residue.

alphabet=<symbols>

Explicit symbol list such as alphabet=ACDFGHIW, one class per letter. Letters must be unique and there may be at most 26. Bits per residue is the smallest number of bits that can hold all classes, so ACDFGHIW uses 3.

alphabet=<preset>

Named preset: legacy (also accepted as amino8), c6, c7, c8, c9, c12, c14, or mi7. A preset supplies both the class letters and the key groups. If key= is also given, its group representatives must match the preset's class letters.

key=

Translation key applied on the fly (no re-encoded FASTA): slash-separated groups, e.g. key=AST/C/DEKNQR/FY/GP/H/ILMV/W (each group collapses to its first letter), or a preset name: legacy (amino8), c6, c7, c8, c9, c12, c14, mi7. Requires an amino alphabet (rejected with alphabet=nt or no alphabet). Output kmers are written in the class letters.

Residues outside the alphabet (X, B, Z, *, gaps) reset the rolling kmer. Packed kmers must fit in 62 bits, so kdesign × bits-per-residue must be at most 62. For example, amino (5 bits) allows kdesign up to 12, and ACDFGHIW (3 bits) allows kdesign up to 20.

Kmer Parameters

k=17

Kmer length used for both selection and output. Must be 1 to 31.

kdesign=

If set, selection runs at this k but output is decomposed to k. Must be between k and 31. For example kdesign=18 k=17 selects 18-mers, then outputs their constituent 17-mers; each covered sequence then has >=2 kmer hits, which enables minkmerhits=2 downstream for free.

Selection Parameters

step=500

Number of kmers selected per round. Must be positive. This is the base value for the stepfraction bounds (minstepmult, maxstepmult).

steps=

Comma-delimited per-round schedule, e.g. steps=200,50,20,10,5. The last value repeats until the coverage target is reached. Sets step to the first value. Mutually exclusive with stepfraction. The script help lists this as nucleotide mode only, but the code applies the schedule in nucleotide mode and in amino and family modes.

stepfraction=0

Adaptive sizing for rounds 2 and later: target this fraction of the remaining sequences, projected from the previous round's recovered-sequences-per-kmer rate. 0 disables adaptation. Must be in [0,1]. Nucleotide mode only; amino and family modes accept the value but do not use it. Mutually exclusive with steps=.

minstepmult=0.1

Lower bound on adaptive step, as a multiple of the initial step. Used only with stepfraction (nucleotide mode).

maxstepmult=2

Upper bound on adaptive step, as a multiple of the initial step. Used only with stepfraction (nucleotide mode).

step2boost=1

Multiplier applied only to the projected second-round step. Used only with stepfraction (nucleotide mode).

maxkmers=

Maximum total kmers to select. 0 means no limit (default 0).

target=0.999

Stop once this fraction of pool sequences is covered.

minhits=1

Evict a sequence only once it contains this many DISTINCT selected kmers. minhits=2 requires two distinct selected kmers per covered member. kdesign=k+1 is the cheaper alternative, but its two kmers overlap. Applies in nucleotide, amino, and family modes.

Family-Batch Parameters

These apply to protein mode (an amino alphabet). families= runs one covering set per family, all in one JVM with families processed in parallel.

families=

A directory of per-family protein FASTAs (family id = file name without .faa, .fa, or .fasta, with an optional .gz) or a manifest TSV of family_id<TAB>path. Relative manifest paths resolve against the manifest's directory. Requires an amino alphabet and summary=. Duplicate family ids are rejected.

summary=<file>

Per-family summary TSV. Required with families=. Columns: family_id, members, excluded, selected_kmers, rounds, coverage, uncovered. It also includes #input lines giving each family's input path and sha80, which is the trailing 20 hex characters of the input file's SHA-256. The out= file then receives the sets TSV (family_id, kmer, selection_rank, original_count, round) with #alphabet, #key, and #k header lines.

exclude=<file>

Member ids (column 1) removed from every family pool before selection, e.g. a held-out query set. Lines starting with # are skipped. Family mode only.

maxfamilies=0

If >0, a kmer present in more than this many families' pools is ineligible for selection (cross-family specificity). Family mode only. The number of removed candidates is written as #cross_family_candidates_removed in both output files. Cannot be combined with streamfamilies=t or consensus=.

commit=

Free-text provenance, written as a #bbtools_commit line in both the sets TSV and the summary TSV (default unknown). Family mode only.

Performance Parameters

In nucleotide mode, kmer counting is multithreaded via a partitioned counter: each thread buffers kmers per partition and only locks a partition briefly to flush a batch, so there is no serial merge step and no single-table size ceiling. These two parameters apply only to nucleotide mode.

partitions=

Number of counter shards. Default: the nearest odd value >= max(15, 2 × threads). Odd avoids aliasing against the structured low bits of 2-bit-packed kmers. More shards means less lock contention between threads and a higher total-distinct-kmer ceiling (each shard is its own table), at the cost of a little fixed memory overhead. Nucleotide mode only.

bufsize=200

Kmers a thread buffers per partition before flushing (taking that partition's lock). Larger reduces lock frequency. Nucleotide mode only.

Java Parameters

-Xmx

Set memory usage. Default is 84% of detected available memory. The pool and kmers are loaded fully into memory rather than streamed (the opt-in streamfamilies=t mode, described below, is the exception for family batches).

Other Parameters (accepted by CoveringSet.java, not in the script help)

consensus=<file>

Protein consensus sequences, one per family id (matched to the first token of each FASTA header). Each family's consensus is added copies= times (or the per-family count from consensuscopies=) to that family's pool before selection. Requires families= and copies>=1. Requires maxfamilies=0.

consensuscopies=<file>

Two-column TSV of family<TAB>count. Overrides copies= per family. Requires consensus=. Every family must have a row.

streamfamilies=f

Opt-in streaming family mode (alias stream=). Loads, scores, and releases one family at a time, so at most one family pool is held in memory. Requires families= and maxfamilies=0. The built-in self-test checks that its output is byte-identical to the default family mode.

verbose=f

Print progress for every round. Otherwise nucleotide mode prints every 10th round.

Aliases

stepschedule= (steps=), stepfrac= or adaptivefraction= (stepfraction=), budget= (maxkmers=), mincov= or mincoverage= (target=), extra1= (extra=), familydir= (families=), numpartitions= (partitions=), partitionbuffer= (bufsize=), bbtools_commit= (commit=), stream= (streamfamilies=).