DeepTaxa Tutorials

A hands-on guide from running predictions to understanding the model architecture

DeepTaxa is a hybrid CNN-BERT model that classifies 16S rRNA gene sequences into a seven-rank taxonomic hierarchy (Domain through Species). These tutorials are intended for researchers in microbial ecology, clinical microbiome research, or machine learning who want to use the pre-trained model, train a custom model, or understand the design choices behind the architecture.

1 Tutorials

The tutorials are independent but build on each other conceptually. For new users, the recommended reading order is Prediction, Ensemble, Validation, Case study, Training, Analysis, then Architecture, with a final QIIME 2 tutorial for running the classifier inside QIIME 2. If you only need to classify sequences with the released model, the Prediction tutorial is a self-contained starting point; if you intend to train your own model, begin with Training.

Tutorial	Scope
Prediction	Classify 16S sequences with the pre-trained model, interpret per-rank accuracy, and examine confidence scores
Ensemble	Combine the five per-region seed checkpoints into a soft-vote ensemble and measure the per-rank gain in weighted F1 over a single model
Validation	Validate the model on mock communities of known composition, comparing genus- and species-level calls with a reference method across V3-V4 and full-length 16S
Case study	Apply DeepTaxa to a real clinical cohort: reanalyze a published ALS gut-microbiome dataset, cross-check the genus assignments against SILVA, and reproduce the original study’s findings
Training	Train a model from scratch on the Greengenes 2 dataset, monitor learning curves, and evaluate the trained checkpoint
Analysis	Evaluate classification performance in depth: confusion patterns, sequence and embedding similarity, calibration, and novel taxa detection
Architecture	Understand the CNN-Transformer fusion, the loss formulation including the optional focal loss, and how to adapt the model to other marker genes
QIIME 2	Run DeepTaxa inside a QIIME 2 workflow: import a model, classify representative sequences into FeatureData[Taxonomy], and train
Glossary	Short explanations of the concepts used across the tutorials, from the 16S rRNA gene to calibration and ensembling

2 Which tutorial should I use?

Start with the page that matches your goal.

• To classify 16S rRNA sequences with a released checkpoint, use Prediction.
• To combine the five released seed checkpoints, use Ensemble.
• To validate DeepTaxa on known mock communities, use Validation.
• To see a real short-read microbiome reanalysis, use Case study.
• To train a model from reference sequences, use Training.
• To evaluate model behavior in depth, use Analysis.
• To understand the model design, use Architecture.
• To run DeepTaxa inside QIIME 2, use QIIME 2.

3 Prerequisites

• Python 3.10 or later
• A CUDA-capable GPU is strongly recommended for training; CPU training is possible but roughly an order of magnitude slower, with the exact ratio depending on the CPU model and core count. Prediction and analysis can run on CPU, though at reduced throughput.

Install DeepTaxa and the packages used for plotting and evaluation. Most users should install from PyPI; Bioconda is convenient for Conda-based toolchains, and a source install is for the latest development version or code changes.

Option 1, PyPI (recommended):

python -m pip install deeptaxa-rrna
python -m pip install matplotlib scikit-learn

Option 2, Bioconda:

conda install -c bioconda deeptaxa-rrna

Option 3, source (development version or code changes):

git clone https://github.com/systems-genomics-lab/deeptaxa.git
cd deeptaxa && python -m pip install .

DeepTaxa is distributed as deeptaxa-rrna on PyPI and Bioconda because the name deeptaxa was already taken by an unrelated package; the import package and the command-line tool are both deeptaxa.

4 Resources

• DeepTaxa source code (GitHub)
• QIIME 2 plugin (q2-deeptaxa) for classifying FeatureData[Sequence] inside QIIME 2
• Pre-trained models (Hugging Face)
• Training data (Greengenes 2)
• Issue tracker
• License (MIT)
• DeepTaxa manuscript (Salah et al., 2026)

5 Troubleshooting

• No GPU detected. Prediction and analysis run on CPU, though more slowly; training requires a CUDA-capable GPU. Confirm the device with python -c "import torch; print(torch.cuda.is_available())".
• CUDA out of memory. Lower the batch size (for example, --batch-size 32 or 16), or run on CPU.
• Checkpoint fails to load. Verify the file path and that the download completed. The checkpoints are about 306 MB; resume a partial transfer with curl -C - -L -O <url>.
• Download interrupted. Add -C - to the curl command to resume, and confirm the Hugging Face URL is reachable.
• Dependency conflicts. Install into a clean environment. DeepTaxa requires Python 3.10 or later and PyTorch 2.4 or later; pip install deeptaxa-rrna pulls compatible versions.

6 How to cite

If you use DeepTaxa in your work, please cite the manuscript (Salah et al., 2026):

@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},
  volume  = {6},
  number  = {1},
  pages   = {vbag166},
  doi     = {10.1093/bioadv/vbag166}
}

References

Salah, R., AbdElaal, K. R., Ghonaim, L., Awe, O. I., & Moustafa, A. (2026). DeepTaxa: A hybrid CNN-BERT framework for 16S rRNA taxonomic classification. Bioinformatics Advances, 6(1), vbag166. https://doi.org/10.1093/bioadv/vbag166