DRAGEN K-mer 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) the reference sequence database is searched and query sequences are classified.
The k-mer classifier supports two types of classification. In taxonomy-based classification, the query sequences are classified to a taxonomic identifier (taxid) associated with a node in a taxonomic tree. In category-based classification, the query sequences are classified to a broader category (e.g. "bacterial"). The type of classification performed depends on whether a taxonomy-based or category-based database is used. The type of database is auto-detected and does not need to be specified in the DRAGEN command.
This guide explains how to run query sequences against a pre-existing reference sequence database; several are available for download. Users can also build their own custom reference sequence database.
Command Line Settings
Required Inputs
--enable-kmer-classifier
Enables the K-mer 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 K-mer 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. In this case, --kmer-classifier-input-read-file should point to a .tsv file that has up to three columns: Sample ID, Read1 file, (optional) Read 2 file. (Default=false).
--kmer-classifier-split-fastq
Set to true to create a set of FASTQ files (depending on the input) with category-specific reads. Compatible only with a category binner database.
--kmer-classifier-min-window
The minimum number of consecutive k-mers to classify a read to a taxid or category. (Default=1).
--kmer-classifier-output-read-seq
Set to true to add a column in the read-level output file with the read sequence. (Default=false).
--kmer-classifier-output-taxid-seq
Set to true to add a column in the read-level output file with the taxid or category assignments for each k-mer. (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
Set to true to not create individual read output. (Default=false).
--kmer-classifier-no-taxid-counts
Set to true to not write taxid count output file. (Default=false).
--kmer-classifier-protein-input
Set to true to indicate protein query sequences. To use this option, the reference sequence database MUST be of protein sequences. (Default=false).
--kmer-classifier-remove-dups
Deduplicate reads so that each unique sequence is analyzed once. Read counts in the output still reflect the non-deduplicated read count. Not supported for paired-end reads. (Default=false).
--kmer-classifier-ncpus
Number of CPUs available for processing.
Example Command Line
Input Files and Options
Input Reads
Applies to: --kmer-classifier-input-read-file, --kmer-classifier-multiple-inputs
If the analysis is for a single 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 k-mer 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 when --kmer-classifier-multiple-inputs=true.
When paired-end samples are analyzed, each read pair is counted as one read in the output files. The k-mer content of both R1 and R2 is considered in order to classify the read.
Read deduplication can be enabled for single-ended samples with --kmer-classifier-remove-dups=true. This will cause each unique sequence to be classified just once, which may increase the speed of classification. The read counts in the output files will still reflect the non-deduplicated read count. Read deduplication is not supported for paired-end reads. If --kmer-classifier-remove-dups is set to true, it will be automatically suppressed for any paired-end samples.
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 k-mer 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 k-mer classifier runs. In this case, it is recommended to set --kmer-classifier-load-db-ram=false.
Taxid JSON Mapping File
Applies to: --kmer-classifier-db-to-taxid-json
This input file is downloaded alongside the reference sequence database. It associates an internal identifier in the database to an external source, like the NCBI taxonomy. This JSON file is a dictionary where the keys are internal identifiers, and is mapped to an external taxid, name, and rank. Example:
The internal identifiers are used in the output files. This JSON file can be used to map the results to taxids from the NCBI taxonomy.
Output Files
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.
1
Read index
integer
2
Read name
string
3
Internal identifier (taxid or category) the read classified to
integer
4
Maximum number of contiguous k-mers that classified to this taxid
integer
5
Score assigned to the classification
integer
6
Number of k-mers that classified to this taxid
integer
7
Read duplication count
integer
8
Name associated with taxid or category, 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
Internal identifier that each k-mer 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 --kmer-classifier-output-read-seq flag is set)
string
Taxid/Category-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 detected taxid. In the case of a category-based database, it summarizes the results for each detected category or category combinations.
db_taxid
Identifier for this taxid/category used internally in the database
integer
duplicity
Ratio of total number of k-mers from reads assigned to this taxid/category compared to the number of distinct k-mers from reads assigned to this taxid/category
float
distinct_coverage
Percent of k-mers in the database assigned to this taxid/category that are covered by k-mers in the reads assigned to this taxid/category
integer
read_count
Number of reads that classified to this taxid/category
integer
total_kmer_count
Number of k-mers that classified to this taxid/category
integer
distinct_kmer_count
Number of distinct k-mers that classified to this taxid/category
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/category, 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 k-mers assigned to this taxid/category from the reference sequences
string
probability_present
Not in use
float
Category Summary Output
If a category binner database is used, an output file will be generated to summarize the composition of the sample. See more details here.
Category-Specific FASTQs
If a category binner database is used, and --kmer-classifier-split-fastq is true, a set of category-specific FASTQs will be generated. See more details here.
Last updated
Was this helpful?