clustkit 0.1.2

Docs · Report Bug · Request Feature

ClustKIT is a bioinformatics tool for protein sequence clustering. It combines MinHash sketching, locality-sensitive hashing (LSH), banded Smith-Waterman alignment with BLOSUM62 scoring, and Leiden community detection to achieve high clustering accuracy at all identity thresholds, including the challenging low-identity regime (30-50%) where greedy heuristic methods lose sensitivity.

Features

• Accurate at low identity: Smith-Waterman alignment with BLOSUM62 scoring and Leiden graph partitioning produce well-connected clusters, especially at thresholds below 50%
• Fast: Multi-stage filtering (LSH + Jaccard pre-filter + length-ratio filter) eliminates >98% of candidate pairs before alignment
• Scalable: C/OpenMP alignment kernel with configurable thread count; optional GPU acceleration via CuPy
• Flexible clustering: Leiden community detection (default), connected components, or greedy

Installation

pip install clustkit

With GPU acceleration (requires CUDA 12.x):

pip install clustkit[gpu]

From source:

git clone https://github.com/JLSteenwyk/ClustKIT.git
cd ClustKIT
pip install -e ".[dev]"

Quick start

# Cluster proteins at 50% identity using 8 threads
clustkit -i proteins.fasta -o output/ -t 0.5 --threads 8

# Use connected components instead of Leiden
clustkit -i proteins.fasta -o output/ -t 0.7 --cluster-method connected --threads 4

# GPU-accelerated alignment
clustkit -i proteins.fasta -o output/ -t 0.3 --device 0 --threads 8

Output files:

• output/clusters.tsv — Cluster assignments (sequence_id, cluster_id, is_representative)
• output/representatives.fasta — Representative sequences
• output/run_info.json — Run parameters and statistics
• output/cluster_size_distribution.png — Size distribution plot (with --plot)

Pipeline overview

ClustKIT clusters sequences through six phases:

1. Read — Parse FASTA/FASTQ, integer-encode sequences
2. Sketch — MinHash bottom-s sketches with adaptive k-mer size
3. LSH — Locality-sensitive hashing to find candidate pairs
4. Align — Banded Smith-Waterman with BLOSUM62 scoring, affine gap penalties, length-ratio and Jaccard pre-filters
5. Graph — Sparse similarity graph construction
6. Cluster — Leiden community detection (default), connected components, or greedy

CLI reference

clustkit   Cluster sequences by identity threshold

Options

Dependencies

Core (installed automatically):

Optional:

License

MIT License. See LICENSE for details.