Kmer Classifier

Description

The metagenomics classifier uses a k-mer based classification algorithm to classify each query sequence (usually a read) against a collection of reference sequences. There are two logical steps to this process: 1) reference sequences are indexed into a searchable database 2) reference sequence database is searched using query sequences and query sequences are classified to taxid(s) associated with the reference sequences. This guide explains how to run query sequences against a pre-existing reference sequence database (As of DRAGEN 4.3+, users can build their own custom reference sequence database).

Command Line Settings

Option	Description
Required Inputs
--enable-kmer-classifier	Enables the Kmer Classifier. (Default=false).
--output-file-prefix	Prefix for all output files.
--output-directory	Directory for all output files.
--kmer-classifier-input-read-file	Input sequence file (zipped or unzipped) to the Kmer Classifier.
--kmer-classifier-db-file	Database of sequences to classify against.
Optional Inputs
--intermediate-results-dir	Area for temporary files. Size must be greater than size of all FASTQ files multiplied by 2.
--kmer-classifier-load-db-ram	Load the database onto RAM. Do not use if database is on ramdisk. (Default=false).
--kmer-classifier-multiple-inputs	Set to true to run with multiple inputs. The input read file is now a .tsv file that has three columns: Sample ID, Read1 file, (optional) Read 2 file. (Default=false).
--kmer-classifier-min-window	The minimum number of consecutive kmers to classify assignment at taxid. (Default=1).
--kmer-classifier-output-read-seq	Option to enable read sequence column in the output file. (Default=false).
--kmer-classifier-output-taxid-seq	Option to enable a taxid string column in the output file. (Default=false).
--kmer-classifier-db-to-taxid-json	Path to JSON file that maps database IDs to external taxids, names, and ranks.
--kmer-classifier-no-read-output	Option to not create individual read output. (Default=false).
--kmer-classifier-no-taxid-counts	Option to not write taxid count output file. (Default=false).
--kmer-classifier-protein-input	Option to indicate protein query sequences. To use this option, the reference sequence database MUST be of protein sequences. (Default=false).
--kmer-classifier-ncpus	Option to set the number of CPUs available for processing.

Example Command Line

dragen \
  --enable-kmer-classifier=true \
  --output-file-prefix <PREFIX> \
  --output-directory <OUTPUT_DIR> \
  --kmer-classifier-input-read-file /path/to/fastq.gz \
  --kmer-classifier-db-file /path/to/database \
  --kmer-classifier-min-window 1 \
  --kmer-classifier-ncpus=2 \
  --kmer-classifier-output-read-seq=false \
  --kmer-classifier-output-taxid-seq=false

Input Details

Input Reads

Applies to: --kmer-classifier-input-read-file, --kmer-classifier-multiple-inputs

If the analysis is for a single FASTA/FASTQ read file, then that filename is input to --kmer-classifier-input-read-file and --kmer-classifier-multiple-inputs=false. However, many read files can be submitted to the Kmer Classifier at one time, minimizing the load time for a large reference sequence database. In this case, the input file must be a .tsv (tab-separated) file with two columns (optionally 3 columns). The first column is a unique ID, the second column is the path to the read file, and the optional third column is the path to the second read file in the case of paired-end reads. The ID is used to distinguish the output files. There is no header line. This .tsv file is the input file to --kmer-classifier-input-read-file and --kmer-classifier-multiple-inputs=true.

Reference Sequences

Applies to: --kmer-classifier-db-file, --kmer-classifier-db-to-taxid-json, --kmer-classifier-load-db-ram

A file of reference sequences (the "database") can be quite large. If the database file is stored on a normal file system, it is recommended that you set --kmer-classifier-load-db-ram=true. This will tell the Kmer Classifier to load the database file into memory for faster analysis. It is also allowable to store the database file on a RAM disk, which reduces load time over many Kmer Classifier runs. In this case, it is recommended to set --kmer-classifier-load-db-ram=false.

DB TaxID JSON Mapping File

Applies to: --kmer-classifier-db-to-taxid-json

This input file is downloaded alongside the reference sequence database. It associates a taxid internal to the classifier database to an external source, like the NCBI taxonomy. This JSON file is a dictionary where the keys are internal taxids, and is mapped to an external taxid, name, and rank. Example:

 {
   "2": {"taxid": 2, "name": "bacteria", "rank": "kingdom"},
   "3": {"taxid": 2697049, "name": "SARS-CoV-2", "rank": "subspecies"},
   "4": {"taxid": 5052, "name": "Aspergillus", "rank": "genus"}
 }

The internal taxids are used in the output files. This JSON file can be used to map the results to taxids from the NCBI taxonomy.

Downloading Reference Sequence Databases and Mapping Files

Genome Database

The genome database includes NCBI RefSeq genomes for human, bacteria, archaea, viruses, and fungi. The December 3 2023 NCBI taxonomy was used to build the database, and the sequences were collected in December 2023.

To download the reference index file and the taxid mapping JSON:

wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.refseq_genomes.v6dh.t6db
wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.refseq_genomes.name_map.json

Genome and NT Database

This database includes the contents of the Genome database and all of the NCBI nucleotide (nt) database. The sequences from the NCBI nucleotide database were collected in July 2023, and the December 3 2023 NCBI taxonomy was used to build the database. Two versions of this database are available for download: One that requires a machine with >= 550GB RAM, and a compressed version that trades approximately 5-10% accuracy for a smaller RAM footprint and requires a machine with >= 225GB RAM.

To download the reference index file and the taxid mapping JSON:

wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.genomes_plus_nt.v6dh.t6db
wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.genomes_plus_nt.name_map.json

To download the compressed reference index file and the taxid mapping JSON:

wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.genomes_plus_nt.compressed.v6dh.t6db
wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.genomes_plus_nt.name_map.json

UniRef90 Database

This database includes all protein sequences of the UniRef90 database. The sequences were collected in March 2024 and the March 28 2024 NCBI taxonomy was used to build the database.

To download the reference index file and the taxid mapping JSON:

wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.u90_all.v6dh.t6db
wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.u90_all.name_map.json

16S database

This database includes full length bacterial 16S sequences from the NCBI. The sequences were collected in April 2024 and the March 28 2024 NCBI taxonomy was used to build the database.

To download the reference index file and the taxid mapping JSON:

wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.16S.v6dh.t6db
wget https://illumina-explify-databases.s3.us-east-1.amazonaws.com/kmer-classifier/dragen-kmer-classifier.16S.name_map.json

Ouput Details

There are two output files, one organized around the reads, and the other organized around the taxids.

Read-level Output

Applies to: --kmer-classifier-output-taxid-seq, --kmer-classifier-output-read-seq The main output file is a .tsv file with the extension .read_classifications.tsv. It has no header line, has tab-separated columns, and can vary in the number of columns depending on command line options. It details the results for each read.

Column	Description	Data Type
1	Read index	integer
2	Read name	string
3	Taxid the read classified to	integer
4	Maximum number of contiguous kmers that classified to this taxid	integer
5	Score assigned to the classification	integer
6	Number of kmers that classified to this taxid	integer
7	Read duplication count	integer
8	Name associated with taxid, if given with --kmer-classifier-db-to-taxid-json	string
9	Taxonomic rank associated with taxid, if given with --kmer-classifier-db-to-taxid-json	string
10	Taxid that each kmer classified to (is output when the --kmer-classifier-output-taxid-seq flag is set)	list of integers separated by commas
11	Read sequence (is output when the the --kmer-classifier-output-read-seq flag is set)	string

TaxID-level Output

The second output file is a .tsv file with the extension .classifier.taxid_kmer_counts.tsv. It has a header line and has tab-separated columns. It summarizes the results for each taxid.

Header	Description	Data Type
db_taxid	Identifier for this taxid used internally in the database	integer
duplicity	Ratio of total number of kmers from reads assigned to this taxid compared to the number of distinct kmers from reads assigned to this taxid	float
distinct_coverage	Percent of kmers in the database assigned to this taxid that are covered by kmers in the reads assigned to this taxid	integer
read_count	Number of reads that classified to this taxid	integer
total_kmer_count	Number of kmers that classified to this taxid	integer
distinct_kmer_count	Number of distinct kmers that classified to this taxid	integer
cumulative_read_count	Cumulative number of reads assigned to this taxid and its taxonomic descendants	integer
taxid	Taxid	integer
name	Name associated with the taxid, if given with --kmer-classifier-db-to-taxid-json	string
rank	Taxonomic rank of the taxid, if given with --kmer-classifier-db-to-taxid-json	string
taxid_distinct_kmer_count	Number of distinct kmers assigned to this taxid from the reference sequences	string
probability_present	Not in use	float