QuickClade

Script: quickclade.sh Package: clade Class: clade.CladeSearcher

Assigns taxonomy to query sequences by comparing kmer frequencies to those in a reference database. Developed for taxonomic assignment of metagenomic bins, but it can also run on a per-sequence basis. QuickClade is extremely fast and uses little memory. It uses a hierarchical k-mer comparison algorithm (3, 4, and 5-mers), GC and strandedness filtering, optional 16S/18S SSU alignment, and optional DDL sketch-based matching for orthogonal confirmation. Accuracy declines for incomplete genomes. k5dif represents the sum of absolute values of differences between 5-mer frequency spectra (range 0-1). Because no marker genes are used, QuickClade should perform similarly for any clade in the reference dataset. While the default reference is taxonomically labeled, you can use any reference, with or without taxonomic labels.

Basic Usage

quickclade.sh query1.fa query2.fa query3.fa
quickclade.sh bins
quickclade.sh contigs.fa percontig out=results.tsv usetree

QuickClade accepts multiple query files or directories as input and processes them either as individual files (one result per file) or on a per-contig basis. Loose file or directory names are also permitted alongside flagged parameters.

Local vs. Server Mode

QuickClade can run in two modes:

Local mode (default): Requires a local reference database. The default reference is refseqA48_with_ribo.spectra.gz, which must be present in the resources/ subdirectory of the BBTools installation. DDL sketch files (e.g. refseqSketchDDL_k25e5b4096.tsv.gz) are auto-discovered from the same directory when sketch mode is enabled.
Server mode (server flag): Sends kmer spectra to a remote server. Enabled automatically if no local reference is found. Use this if you do not have a local copy of the database.

Presets

Three preset modes configure multiple parameters at once. Presets are applied first; individual flags specified after can override them.

fast: records=1, buffer=1, callssu=f, sketch=f. Fastest mode.
medium: records=5, buffer=20, callssu=t, sketch=t. Default behavior.
slow: records=10, buffer=50, callssu=t, sketch=t, index=t. Automatically increases memory to 12g unless -Xmx is explicit.

Parameters

Parameters are organized by their function. All parameters from the current shell script are documented.

File Parameters

in=<file,file>: Query files or directories. Loose file or directory names are also permitted. Input can be fasta, fastq, or spectra files; spectra files are made by cladeloader.sh.
ref=<file,file>: Reference files. The current default is refseqA48_with_ribo.spectra.gz in the resources directory. It is plaintext, human-readable, and relatively small.
out=stdout: Set to a file to redirect output. Only query results are written here; progress messages still go to stderr.
composition=: Output a taxonomy composition report to this file. Shows per-level tables with bases, sequences, and percentages. Use composition=stdout to print to screen after results. Best used with percontig or multiple input files. summary= is an alias.
server: Send kmer spectra to a remote server instead of using a local reference. Enabled automatically if no local reference is found. Use this flag when you do not have a local database installed.

Presets

Presets override individual settings and can be further overridden by later flags on the command line.

fast: Sets records=1, buffer=1, callssu=f, sketch=f. Fastest mode; minimal hits reported.
medium: Sets records=5, buffer=20, callssu=t, sketch=t. Default behavior.
slow: Sets records=10, buffer=50, callssu=t, sketch=t, index=t. Automatically increases memory to 12g unless -Xmx is explicit.

Basic Parameters

percontig: Run one query per contig instead of per file. Enables more granular per-sequence taxonomic assignment within multi-contig files.
perfile: Opposite of percontig (default). One query result per input file.
minlen=0: Ignore sequences shorter than this in percontig mode. Helps filter short contigs that may not provide reliable taxonomic signal.
records=5: Print this many top hits per query. Sets both cladehits and sketchhits together as a convenience parameter.
cladehits=5: Maximum clade-based hits to display per query. Independent of sketchhits.
sketchhits=5: Maximum sketch-based hits to display per query. Only applies when sketch=t and index=t.
buffer=20: Internal candidate buffer size for ranking. A larger buffer finds better top hits because SSU alignment is evaluated lazily. Only affects clade hits, not sketch hits.
steps=6: Only search up to this many GC intervals (of 0.01) away from the query GC. Limits search space by GC content proximity for faster processing.
callssu=t: Call 16S and 18S for alignment to reference SSU. Slightly slower but affects top hit ordering. Default is true for medium and slow presets.
server=f: Send spectra to a remote server instead of using a local reference. Enabled automatically if there is no local reference.

Output Format

format=human

Output format. Options:

human: Multi-line per hit, human-readable.
machine: One line per hit, tab-delimited with header. Color off by default.
tabular: Compact one-line per hit with column headers.

showrecords=t

Set to false to suppress per-record output. Useful with composition= when you only want the taxonomy summary.

color=t

ANSI color coding of hits by taxonomic level. On by default for human and tabular formats; off by default for machine format.

colorlevel=

Taxonomic level for color grouping (default family). Hits in the same family get the same color; off-family hits are visually distinct.

showloading=t

Print loading progress messages to stderr. Set to false to suppress index, sketch, and query loading messages.

Taxonomy Filtering

level=: Filter hits by taxonomic level (e.g. level=family). Shows only the best hit per taxon at that level — instead of 7 E. coli strains you see the best hit from each family. Constrained to hits within the buffer.
topcount=10: Maximum entries per taxonomic level in the composition report.
minfraction=0: Minimum fraction (0-1) to include in the composition report. Useful for suppressing rare taxa.

Proxy Parameters

proxyhost=<addr>: HTTPS proxy hostname for environments that require a proxy to reach external servers. Sets -Dhttps.proxyHost for the Java process.
proxyport=<num>: HTTPS proxy port number. Sets -Dhttps.proxyPort for the Java process.

DDL Sketch Parameters

DDL (DynamicDemiLog) sketches provide cardinality-based matching that is orthogonal to the standard kmer frequency comparison, giving a second line of evidence for taxonomic assignment.

sketch=t: Enable sketch-based matching using DDL cardinality profiles. Auto-discovers the best available DDL sketch file from the resources directory (e.g. refseqSketchDDL_k25e5b4096.tsv.gz). Also builds a DDL sketch from each query for comparison. ddl=t is an alias.
sketchfile=: Path to a specific DDL sketch file. Overrides auto-discovery. ddlfile= and sketchref= are aliases.
sketchindex=f: Build an index from DDL sketches. This allows hits by 25-mer matching, orthogonal to the clade index, enabling LCA (lowest common ancestor) calculation. Implies sketch=t. Increases memory usage; slow preset enables this automatically.
minsketchhits=5: Minimum matching DDL buckets required to report a sketch hit.
ddlk=25: K-mer length for DDL sketches.
ddlbuckets=4096: Number of buckets in DDL sketches.

Threading Parameters

loadthreads=auto: Number of threads for parsing reference spectra. By default uses all available threads.
ddlloadthreads=auto: Number of threads for loading DDL sketch files. DDL files load in parallel when multiple are present; this controls the total thread budget across all files.
comparethreads=auto: Number of threads for query comparisons.
parallelsetup=t: Load tree, reference index, and queries in parallel for faster startup. Disable with parallelsetup=f for lower peak memory usage.

Advanced Parameters (mainly for benchmarking)

printmetrics: Output accuracy statistics. Mainly useful for labeled data. Labeled data should have tid_1234 or similar in the header. Works best with usetree.
printqtid: Print query TaxID. Useful for evaluation when query sequences have known taxonomic identifiers.
banself: Ignore records with the same TaxID as the query. Makes the program behave as if that organism is not in the reference. Useful for leave-one-out cross-validation.
simd: Use vector instructions to accelerate comparisons (SIMD hardware acceleration).
maxk=5: Can be set to 4 or 3 to restrict kmer frequency comparisons to smaller kmers. May improve accuracy for small sequences or bins, but slightly reduces accuracy for large ones.
ccm=1.2: Threshold for using pentamers; lower is faster. Controls when 5-mer comparisons are performed.
ccm2=1.6: Threshold for using tetramers. Controls when 4-mer comparisons are performed.
gcdif=0.04: Initial maximum GC difference. Sets the tolerance for GC content differences between query and reference sequences during initial candidate screening.
gcmult=0.5: Max GC difference as a fraction of best 5-mer difference. Dynamically adjusts GC tolerance based on k-mer similarity.
strdif=0.12: Initial maximum strandedness difference. Controls tolerance for differences in strand bias between sequences.
strmult=1.2: Max strandedness difference as a fraction of best 5-mer difference. Dynamically adjusts strand bias tolerance.
hhdif=0.025: Maximum HH metric difference for candidate screening.
cagadif=0.017: Maximum CAGA metric difference for candidate screening.
hhmult=0.5: Max HH difference as a fraction of best 5-mer difference.
cagamult=0.8: Max CAGA difference as a fraction of best 5-mer difference.
ee=t: Early exit; increases speed. Enables early termination of comparisons when sufficient confidence is achieved.
entropy: Calculate entropy for queries. Slow; negligible utility. Computes sequence complexity metrics.
usetree: Load a taxonomic tree for better grading of labeled data. Enables phylogenetically-aware evaluation metrics.
aligner=quantum: SSU alignment algorithm. Options include ssa2, glocal, drifting, banded, crosscut.

Distance Metrics

abs: Use absolute difference of kmer frequencies (L1 distance).
cos: Use 1-cosine similarity of kmer frequencies. Emphasizes relative composition over absolute counts.
euc: Use Euclidean distance (L2 distance) between kmer frequency vectors.
hel: Use Hellinger distance. Treats kmer frequencies as probability distributions.
abscomp: GC-compensated version of abs (default). Uses absolute difference with GC content normalization to reduce compositional bias.

Note: The distance metric strongly impacts ccm, gcmult, and strmult. Defaults are optimized for abscomp.

Java Parameters

-Xmx: Set Java's memory usage. Default is 4g; slow preset automatically uses 12g. Example: -Xmx8g.
-eoom: Exit if an out-of-memory exception occurs. Requires Java 8u92+.
-da: Disable assertions.

Examples

Basic Taxonomic Assignment

quickclade.sh query1.fa query2.fa query3.fa

Assigns taxonomy to multiple query files using the default reference database with medium preset defaults (records=5, sketch=t, callssu=t).

Directory of Bins

quickclade.sh bins

Processes all sequence files in the bins directory. Each file is treated as a separate query (one result per bin).

Per-Contig Analysis with Output File

quickclade.sh contigs.fa percontig out=results.tsv usetree

Analyzes each contig separately, writes results to a tab-delimited file, and loads a taxonomic tree for evaluation of labeled data.

Server Mode (No Local Database Required)

quickclade.sh query.fa server out=results.txt

Sends kmer spectra to the remote QuickClade server. Use when you do not have a local copy of the reference database. Enabled automatically if no local reference is found.

Server Mode with Proxy

quickclade.sh query.fa server proxyhost=proxy.example.com proxyport=3128 out=results.txt

Server mode through an HTTPS proxy. Required in some institutional or HPC environments.

Fast Preset for Quick Screening

quickclade.sh bins fast out=quick_screen.tsv format=tabular

Uses the fast preset (records=1, no SSU, no sketch) for rapid screening of many bins. Tabular output is compact and easy to parse downstream.

Slow (High-Quality) Mode

quickclade.sh bins slow out=detailed.tsv format=human

Uses the slow preset for maximum accuracy. Automatically allocates 12g of memory. Includes DDL sketch index for LCA-based orthogonal hits.

DDL Sketch Matching with Index

quickclade.sh query.fa sketch sketchindex records=10 out=results.tsv

Enables DDL sketch matching and builds an index for 25-mer-based LCA calculation. Reports up to 10 top hits from both clade and sketch sources.

Tabular Output with Color

quickclade.sh contigs.fa percontig format=tabular colorlevel=genus out=results.tsv

Compact one-line-per-hit tabular output with hits colored by genus grouping for easy visual scanning.

Composition Report Only

quickclade.sh assembly.fa percontig showrecords=f composition=stdout topcount=20

Suppresses per-record output and prints only the taxonomy composition summary to the screen, showing up to 20 entries per level.

Composition to File with Machine Output

quickclade.sh bins format=machine out=hits.tsv composition=summary.txt minfraction=0.01

Writes machine-readable hit data to one file and a taxonomy composition summary to another. Composition excludes taxa comprising less than 1% of the total.

Level Filtering to Deduplicate by Family

quickclade.sh query.fa level=family records=10 out=family_hits.tsv

Reports the best hit per family, so instead of multiple strains of the same species you see the best representative from each family in the top 10 candidates.

Benchmarking with Metrics

quickclade.sh printmetrics usetree genomesdir out=null includeself=f

Standard accuracy evaluation workflow on labeled data. Sequences should have tid_1234-style TaxIDs in their headers.

Leave-One-Out Evaluation

quickclade.sh labeled_queries.fa printmetrics usetree banself out=evaluation.txt

Evaluates performance using labeled queries, excluding self-matches so each organism is classified as if it were absent from the reference.

Algorithm Details

K-mer Frequency Profiling

QuickClade uses a hierarchical k-mer frequency comparison working at 3, 4, and 5-mer resolution. The comparison pipeline applies a cascade of screening thresholds:

GC filtering: Only candidates within gcdif GC distance (expanded dynamically by gcmult) are advanced.
Strandedness filtering: Candidates must pass the strdif/strmult strandedness check.
HH and CAGA metrics: Additional discriminative metrics (hhdif, cagadif, hhmult, cagamult) filter candidates before expensive 5-mer comparison.
Pentamer screening (ccm): Threshold for committing to full 5-mer comparison; ccm2 governs 4-mer comparison.
Early exit (ee=t): Terminates comparison loops once sufficient confidence is reached.

DDL Sketch Integration

When sketch=t, QuickClade builds a DDL (DynamicDemiLog) cardinality sketch for each query and compares it against a pre-built sketch database. DDL sketches capture approximate kmer cardinality profiles in compact bucketed form. This approach is entirely orthogonal to the frequency-spectrum comparison, providing independent confirmation of taxonomy. When sketchindex=t (slow preset), an index over the sketch database enables LCA computation for an additional taxonomic assignment signal.

Composite Score

Results are ranked by a composite score that combines the kmer frequency distance, SSU alignment score (when callssu=t), and DDL sketch similarity (when sketch=t). The composite score is shown in the output alongside the individual component scores.

SSU Calling

When callssu=t, QuickClade detects 16S and 18S ribosomal RNA sequences in the query and aligns them to SSU sequences in the reference. This provides a marker-gene signal that refines the ordering of top hits without requiring a separate SSU database. The aligner can be changed with the aligner parameter.

Buffer and Candidate Selection

The buffer parameter controls how many candidates are retained internally before final ranking. SSU alignment is only evaluated for candidates in the buffer (lazy evaluation). A larger buffer means more candidates get SSU-scored, improving hit quality at the cost of speed. Sketch hits bypass the buffer entirely.

Memory and Threading

QuickClade uses 4g by default (12g for slow preset). Reference spectra are loaded with multiple threads (loadthreads), DDL sketch files load in parallel (ddlloadthreads), and queries are compared in parallel (comparethreads). With parallelsetup=t, index loading and query loading overlap to minimize wall time.

Local Database Setup

To run QuickClade in local mode you need the following files in the resources/ directory of your BBTools installation:

Spectra reference (required): refseqA48_with_ribo.spectra.gz — kmer frequency spectra for all reference genomes. This is the main clade comparison database.
DDL sketch file (for sketch mode): e.g. refseqSketchDDL_k25e5b4096.tsv.gz — auto-discovered from resources/ when sketch=t.

If these files are not present, QuickClade will automatically fall back to server mode. To build custom DDL sketch databases, see ddlwriter.sh.

Support

For questions and support:

Email: bbushnell@lbl.gov
Documentation: bbmap.org