q2-kmerizer

A QIIME 2 plugin for generating and working with kmers from biological sequence information.

Installation instructions¶

The easiest way to install and use q2-kmerizer is to install QIIME 2. q2-kmerizer has been included in the QIIME 2 distribution starting with release 2025.10. You can also install with pip, e.g., if you are using a custom rachis environment :

pip install q2_kmerizer@git+https://github.com/bokulich-lab/q2-kmerizer.git@main

To confirm that q2-kmerizer is installed in your QIIME 2/rachis environment, run the following command in your terminal:

qiime kmerizer --help

Examples¶

As an example test, we will use data from Sampson et al, 2016, a study testing whether the fecal microbiome contributed to the development of Parkinson’s Disease (PD).

First we will download the test data:

wget https://data.qiime2.org/2024.10/tutorials/pd-mice/sample_metadata.tsv
wget https://docs.qiime2.org/2024.10/data/tutorials/pd-mice/dada2_table.qza
wget https://docs.qiime2.org/2024.10/data/tutorials/pd-mice/dada2_rep_set.qza

We can count kmer frequencies per sample with this command:

qiime kmerizer seqs-to-kmers \
    --i-sequences dada2_rep_set.qza \
    --i-table dada2_table.qza \
    --o-kmer-table kmer_table.qza \
    --p-max-features 5000

Or run this pipeline to count kmer frequencies, calculate diversity metrics, and create an interactive scatterplot with the results:

qiime kmerizer core-metrics \
    --i-sequences dada2_rep_set.qza \
    --i-table dada2_table.qza \
    --p-sampling-depth 1000 \
    --m-metadata-file sample_metadata.tsv \
    --p-color-by-group donor \
    --p-max-features 5000 \
    --output-dir core-metrics/

Both of these actions output a frequency table that contains kmer counts per sample. This can be used like any other frequency table and passed to any action in QIIME 2 that accepts a frequency table (except for those that also require additional inputs that must match the features in the table, e.g., that require a taxonomy). For example, we can run a pipeline to train a Random Forest classifier and test on a hold-out subset of the dataset (note: this analysis is done purely for demonstrative purposes; the sample size in this test dataset is much smaller than would be required for a robust supervised learning analysis, and proper replicate handling should be done to avoid data leakage).

qiime sample-classifier classify-samples \
    --i-table kmer_table.qza \
    --m-metadata-file sample_metadata.tsv \
    --m-metadata-column donor \
    --output-dir sample-classifier/

About¶

The q2-kmerizer Python package was created from a template. To learn more about q2-kmerizer, refer to the project website. To learn how to use QIIME 2, refer to the QIIME 2 User Documentation. To learn QIIME 2 plugin development, refer to Developing with QIIME 2.

q2-kmerizer is a QIIME 2 plugin. For questions, comments, or feature requests about this plugin, please post in the Community Plugins category on the QIIME 2 Forum. The issue tracker on the GitHub repository is intended for use by the plugin developers and maintainers, not as a help forum.

Citation¶

If you use q2-kmerizer in your work, please cite the following article:

Bokulich NA. 2024. Integrating sequence composition information into microbial diversity analyses with k-mer frequency counting. mSystems:e01550-24. https://doi.org/10.1128/msystems.01550-24