DeepTaxa

DeepTaxa is a deep learning framework for hierarchical taxonomic classification of 16S rRNA gene sequences. It classifies sequences into all seven taxonomic ranks (Domain through Species) in a single forward pass, achieving 92.95% species-level accuracy (5-seed mean) on the Greengenes2 2024.09 test set.

---

Table of Contents

1. Performance
2. Installation
3. Quick Start
4. Data and Pre-Trained Models
5. Training
6. Experimentation
7. Scripts
8. Tutorials
9. QIIME 2 plugin
10. License
11. Citation
12. Contact
13. Acknowledgements

---

Performance

The v2 full-length checkpoints achieve the following on 69,335 held-out test sequences from Greengenes2 2024.09 (5-seed mean across seeds 42, 123, 456, 789, 1011):

Rank	Accuracy	F1	ECE
Domain	99.98%	99.98%	0.0002
Phylum	99.70%	99.69%	0.0022
Class	99.63%	99.59%	0.0024
Order	99.06%	98.96%	0.0057
Family	98.61%	98.41%	0.0074
Genus	96.87%	96.44%	0.0145
Species	92.95%	92.08%	0.0242

Cross-seed standard deviation is at most 0.0004 F1 at every rank (species std 0.0004 F1 / 0.03 percentage points accuracy), demonstrating high reproducibility.

The table above reports the 5-seed mean. Each region ships all five seeds for ensembling, along with a default single model (deeptaxa-full-length-v2.pt, a copy of the seed-42 checkpoint) for users who need only one model.

Architecture

Component	Configuration
CNN	embed_dim=896, 256 filters, kernels [3, 5, 7], 1 conv layer
BERT	4 layers, 7 heads, hidden=896, FFN=3584, GELU, random init
Fusion	Learnable alpha/beta weights + BERT residual connection
Training	Cross-entropy loss, LR=5e-4, batch=64, dropout=0.20, 10 epochs

Three architectures are available:

• HybridCNNBERTClassifier (default): Fuses CNN local motif features with BERT global context. Used for the published checkpoints.
• CNNClassifier: Multi-kernel convolutional network only. Faster training, slightly lower species accuracy.
• BERTClassifier: Transformer encoder only. On its own, a from-scratch transformer underperforms substantially at the species rank; provided mainly for ablation.

Pre-Trained Checkpoints

Three model families (full-length, V3-V4, V4) are hosted on Hugging Face. As of the v2 release each family ships all five seeds (deeptaxa-<region>-v2-seed{42,123,456,789,1011}.pt) for ensembling, plus a default single model (deeptaxa-<region>-v2.pt, a copy of the seed-42 checkpoint):

Default checkpoint	Training data	Species accuracy	Parameters
deeptaxa-full-length-v2.pt	Full-length 16S (277,336 sequences, ~1,500 bp)	92.95% (5-seed mean)	76.4 M
deeptaxa-v3v4-v2.pt	In-silico V3-V4 amplicons (341F/805R, ~420 bp, 273,003 amplicons)	87.54% (5-seed mean)	75.8 M
deeptaxa-v4-v2.pt	In-silico V4 amplicons (515F/806R, ~253 bp, 274,509 amplicons)	82.84% (5-seed mean)	76.4 M

All three families share the same compact architecture. The V4 family keeps the full 16,909-species label space (V4 amplicons extract at 99 percent yield) and matches the full-length parameter count, while the V3-V4 model is slightly smaller because its per-rank heads cover a smaller species vocabulary (8,347 vs 16,909). A config.json with full model metadata is also available. The v1 checkpoints remain available in the same repository.

Each checkpoint records its own seed in a seed field, so the ensemble members are self-identifying. For the best accuracy and calibration, average the per-rank softmax probabilities of all five seed checkpoints for a region and take the argmax at each rank (see scripts/ensemble_predict.py). This soft-vote ensemble improves species F1 over a single seed in every region, with larger gains at the finer ranks:

Region	Single-seed species F1	5-seed ensemble species F1
Full-length	0.9213	0.9330
V3-V4	0.8588	0.8698
V4	0.8016	0.8110

---

Installation

DeepTaxa requires Python 3.10 or later. It is distributed as deeptaxa-rrna on PyPI and Bioconda (the bare deeptaxa name was already taken on PyPI by an unrelated tool); the import package and the command-line tool are both deeptaxa.

From PyPI

pip install deeptaxa-rrna
deeptaxa --version

From Bioconda

conda install -c bioconda deeptaxa-rrna
deeptaxa --version

From source

For the latest development version, or to modify the code:

git clone https://github.com/systems-genomics-lab/deeptaxa.git
cd deeptaxa
conda create --name deeptaxa_env python=3.10 -y
conda activate deeptaxa_env
pip install .
deeptaxa --version

Dependencies (torch, transformers, pandas, numpy, scikit-learn, biopython, h5py, optuna, etc.) are specified in pyproject.toml and installed automatically.

Note: For GPU support, install a CUDA-compatible PyTorch build before installing DeepTaxa. See the PyTorch installation guide.

---

Quick Start

Predict with the pre-trained model (no training data needed):

# Download the checkpoint
mkdir -p ../deeptaxa-data/models
wget -P ../deeptaxa-data/models \
  https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-full-length-v2.pt

# Classify sequences
deeptaxa predict \
  --fasta-file your_sequences.fna \
  --checkpoint ../deeptaxa-data/models/deeptaxa-full-length-v2.pt \
  --output-dir ../deeptaxa-outputs/predictions

Evaluate against known labels (adds per-rank accuracy, F1, ECE to the output):

deeptaxa predict \
  --fasta-file ../deeptaxa-data/greengenes/gg_2024_09_testing.fna.gz \
  --taxonomy-file ../deeptaxa-data/greengenes/gg_2024_09_testing.tsv.gz \
  --checkpoint ../deeptaxa-data/models/deeptaxa-full-length-v2.pt \
  --output-dir ../deeptaxa-outputs/evaluation

Inspect a checkpoint:

deeptaxa describe \
  --checkpoint ../deeptaxa-data/models/deeptaxa-full-length-v2.pt

Tip: Run deeptaxa train --help or deeptaxa predict --help for a full list of options.

---

Data and Pre-Trained Models

Datasets and checkpoints are hosted on Hugging Face. Store them in a sibling directory outside the codebase:

working_directory/
├── deeptaxa/              # This repository
├── deeptaxa-data/         # Datasets and checkpoints
│   ├── greengenes/
│   │   ├── gg_2024_09_training.fna.gz    (277,336 sequences, ~96 MB)
│   │   ├── gg_2024_09_training.tsv.gz    (taxonomy labels, ~2.6 MB)
│   │   ├── gg_2024_09_testing.fna.gz     (69,335 sequences, ~24 MB)
│   │   └── gg_2024_09_testing.tsv.gz     (taxonomy labels, ~0.8 MB)
│   └── models/
│       ├── deeptaxa-full-length-v2.pt
│       ├── deeptaxa-v3v4-v2.pt
│       └── deeptaxa-v4-v2.pt
└── deeptaxa-outputs/      # Training and prediction outputs

DeepTaxa uses the Greengenes2 database (2024.09 release), reformatted and hosted on Hugging Face.

Download

# Dataset
mkdir -p ../deeptaxa-data/greengenes && cd ../deeptaxa-data/greengenes
for f in gg_2024_09_training.fna.gz gg_2024_09_training.tsv.gz \
         gg_2024_09_testing.fna.gz gg_2024_09_testing.tsv.gz; do
  wget https://huggingface.co/datasets/systems-genomics-lab/greengenes/resolve/main/$f
done

# Checkpoints
mkdir -p ../models && cd ../models
wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-full-length-v2.pt
wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-v3v4-v2.pt
wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-v4-v2.pt
wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/config.json

# To ensemble, download all five seeds for a region (example: full-length)
for s in 42 123 456 789 1011; do
  wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-full-length-v2-seed${s}.pt
done

Tip: If wget is unavailable (for example, on macOS), substitute curl -L -O from within the target directory to download each file.

Note: Checkpoint files use PyTorch's pickle-based serialization. Download them only from the official Hugging Face repository.

---

Training

All architecture hyperparameters default to the published (compact) configuration, so a minimal training command uses the same architecture and hyperparameters as the published checkpoint (exact numbers still depend on the seed, hardware, and package versions):

deeptaxa train \
  --fasta-file ../deeptaxa-data/greengenes/gg_2024_09_training.fna.gz \
  --taxonomy-file ../deeptaxa-data/greengenes/gg_2024_09_training.tsv.gz \
  --model-type hybridcnnbert \
  --output-dir ../deeptaxa-outputs/

Training takes approximately 1 h 20 m on an NVIDIA RTX 4090 (or 2 h 35 m on an NVIDIA A40) for 10 epochs.

Output

Each training run produces:

• checkpoints/deeptaxa_<uuid>_epoch<N>.pt: Model weights, optimizer state, scheduler state, and label encoders for each epoch.
• metrics/deeptaxa_<uuid>_epoch<N>.json: Per-epoch validation loss, accuracy, F1, precision, and recall at each rank.
• deeptaxa_uuid.txt: The unique run identifier.

Early Stopping

To stop training when validation loss plateaus:

deeptaxa train \
  --fasta-file ../deeptaxa-data/greengenes/gg_2024_09_training.fna.gz \
  --taxonomy-file ../deeptaxa-data/greengenes/gg_2024_09_training.tsv.gz \
  --model-type hybridcnnbert \
  --epochs 20 \
  --early-stopping-patience 3 \
  --output-dir ../deeptaxa-outputs/

Setting --early-stopping-patience 0 (the default) disables early stopping.

---

Experimentation

The default configuration uses DNABERT-2 tokenization, cross-entropy loss, and uniform rank weighting. Each choice can be varied independently for ablation studies.

Encoding comparison

# Default: DNABERT-2 BPE tokenization
deeptaxa train --model-type cnn --encoding dnabert ...

# Ablation: one-hot nucleotide encoding (4-channel, no pretrained tokenizer)
deeptaxa train --model-type cnn --encoding onehot ...

Loss function comparison

# Default: cross-entropy
deeptaxa train --model-type hybridcnnbert --loss-type cross_entropy ...

# Ablation: focal loss (gamma=2.0)
deeptaxa train --model-type hybridcnnbert --loss-type focal --focal-gamma 2.0 ...

Architecture comparison

Train CNN-only, BERT-only, or the hybrid under the same data and hyperparameters using --model-type cnn, --model-type bert, or --model-type hybridcnnbert.

Calibration

When --taxonomy-file is provided at prediction time, DeepTaxa computes Expected Calibration Error (ECE) alongside accuracy, F1, precision, recall, and AUC. ECE measures the gap between predicted confidence and observed accuracy across 10 equal-width bins. All metrics are saved to metrics.json.

---

Scripts

The scripts/ directory contains reusable tools for common workflows:

Script	Purpose
deeptaxa_workflow.sh	End-to-end workflow: train, resume, describe, predict
run_experiment.sh	Central experiment runner with logging and timing
run_ablation.sh	Ablation study: architecture, encoding, and loss variants
run_amplicon_eval.sh	Simulated amplicon evaluation (V3-V4, V4)
run_similarity_eval.sh	Similarity-stratified evaluation using vsearch
calibration_diagnosis.sh	A/B comparison of temperature configurations
calibration_sweep.sh	Multi-configuration temperature sweep
simulate_amplicons.py	Extract amplicon regions via in-silico PCR
ensemble_predict.py	Evaluate the five-seed soft-vote ensemble against the test set
sequence_similarity.py	Compute train-test nearest-neighbor identity
similarity_curve.py	Plot accuracy stratified by train-test similarity

---

Tutorials

Interactive tutorials with executable code are published at systems-genomics-lab.github.io/deeptaxa:

• Prediction: Classify sequences with the pre-trained model
• Validation: Validate on mock communities of known composition
• Case study: Reanalyze a published ALS gut-microbiome dataset
• Training: Train from scratch on Greengenes2
• Analysis: Evaluate performance, calibration, and error patterns
• Architecture: Model internals and extensibility

---

QIIME 2 plugin

DeepTaxa comes with a QIIME 2 plugin (q2-deeptaxa) so you can run it inside QIIME 2 workflows. The plugin is part of the package, so there is nothing extra to install. In an activated QIIME 2 environment, install DeepTaxa from Bioconda and refresh the plugin cache:

conda install -c bioconda deeptaxa-rrna
qiime dev refresh-cache
qiime deeptaxa --help

A trained model is a QIIME 2 artifact of semantic type DeepTaxaModel, so its provenance is tracked like any other artifact. Download a published checkpoint that matches your amplicon region from the model repository (deeptaxa-full-length-v2.pt for full-length 16S, deeptaxa-v3v4-v2.pt for V3-V4, deeptaxa-v4-v2.pt for V4), then import it once:

qiime tools import \
  --type DeepTaxaModel \
  --input-path deeptaxa-full-length-v2.pt \
  --input-format DeepTaxaModelFormat \
  --output-path deeptaxa-model.qza

A DeepTaxaModel wraps a PyTorch checkpoint, which is loaded with pickle. Loading a checkpoint runs whatever code it was saved with, so only import model files from a source you trust (the same caution applies to any PyTorch model, or to a scikit-learn classifier in QIIME 2).

Classify the representative sequences from your workflow (for example rep-seqs.qza from DADA2 or Deblur):

qiime deeptaxa classify \
  --i-reads rep-seqs.qza \
  --i-classifier deeptaxa-model.qza \
  --o-classification taxonomy.qza

Like classify-sklearn, classify trims each lineage at a confidence of 0.7 by default, so only the confident part of the assignment is reported. Adjust the threshold with --p-confidence, or pass --p-confidence disable to keep all seven ranks:

# Keep the full seven-rank lineage instead of trimming
qiime deeptaxa classify \
  --i-reads rep-seqs.qza \
  --i-classifier deeptaxa-model.qza \
  --p-confidence disable \
  --o-classification taxonomy.qza

The result is an ordinary FeatureData[Taxonomy], so it feeds into the rest of QIIME just like the output of any other classifier, such as a taxonomy bar plot:

qiime taxa barplot \
  --i-table table.qza \
  --i-taxonomy taxonomy.qza \
  --m-metadata-file metadata.tsv \
  --o-visualization taxa-bar-plots.qzv

You can also summarize a model, or train a new one from reference sequences and their taxonomy (training is a heavy job, so a GPU is recommended):

# Summarize a model
qiime deeptaxa describe \
  --i-classifier deeptaxa-model.qza \
  --o-visualization model-summary.qzv

# Train a new model
qiime deeptaxa fit \
  --i-reference-reads ref-seqs.qza \
  --i-reference-taxonomy ref-taxonomy.qza \
  --p-epochs 10 \
  --o-classifier deeptaxa-model.qza

fit trains on the seven standard ranks (domain through species). Each reference lineage is mapped onto those ranks by prefix (d__ or k__ for domain, then p__ c__ o__ f__ g__ s__); any rank missing from a lineage is recorded as Unclassified.

The plugin needs a QIIME 2 distribution that provides q2-types, such as the amplicon distribution. With a threshold in effect (the default), the Confidence column holds the score of the deepest rank that was kept; with --p-confidence disable, it holds the lowest per-rank softmax probability along the full lineage, a cautious score for the whole assignment.

The plugin was tested with the QIIME 2 amplicon 2024.10 distribution, installed through conda as shown above. classify runs on either CPU or GPU; whether you get a GPU build of PyTorch depends on what conda resolves for your QIIME 2 release, so for heavy training jobs you may prefer the native deeptaxa train command (see Training) on a GPU machine.

---

License

• Code and models: MIT License
• Greengenes dataset: Modified BSD License

---

Citation

If DeepTaxa contributes to your research, please cite our paper in Bioinformatics Advances: https://doi.org/10.1093/bioadv/vbag166

@article{salah2026deeptaxa,
  title={{DeepTaxa}: A Hybrid {CNN}-{BERT} Framework for {16S} {rRNA} Taxonomic Classification},
  author={Salah, Rana and AbdElaal, Khlood R. and Ghonaim, Lobna and Awe, Olaitan I. and Moustafa, Ahmed},
  journal={Bioinformatics Advances},
  year={2026},
  doi={10.1093/bioadv/vbag166},
  publisher={Oxford University Press}
}

For the Greengenes dataset:

@article{mcdonald2024greengenes,
  title={Greengenes2 unifies microbial data in a single reference tree},
  author={McDonald, Daniel and Jiang, Yueyu and Balaban, Metin and others},
  journal={Nature Biotechnology},
  volume={42},
  pages={715--718},
  year={2024},
  doi={10.1038/s41587-023-01845-1}
}

---

Contact

To report bugs, suggest features, or contribute code, open an issue on GitHub.

---

Acknowledgements

• Ahmed A. El Hosseiny and the High-Performance Computing Team of the School of Sciences and Engineering at the American University in Cairo for GPU access that enabled this work.
• Hugging Face for hosting datasets and models.