DeepTaxa Tutorial: Classifying Full-Length 16S ASVs to the Species Level and Validating Against a Mock Community
Open In Colab
Many microbiome questions need species-level resolution, not just genus, but a single hypervariable region rarely carries enough signal to reach it. The full-length 16S gene carries more, so full-length sequencing, for example with PacBio circular consensus reads, allows finer assignment. This notebook examines that with DeepTaxa on full-length ASVs from the ZymoBIOMICS standard, assessing how reliably species can be named when the composition is already known. The steps are the same as for V3-V4, with the full-length checkpoint and a closer look at species.
The sample is the ZymoBIOMICS standard sequenced as full-length 16S on a PacBio Revio instrument (accession SRR38028391). The analysis begins from ASVs produced with the DADA2 PacBio workflow, summarized in the Appendix. The eight species are known, so accuracy can be measured directly.
1 Install
!pip install -q deeptaxa-rrnaimport pandas as pd, torchif torch.cuda.is_available(): g = torch.cuda.get_device_properties(0)print(f"GPU: {g.name}, {g.total_memory //1024**3} GB, compute {g.major}.{g.minor}, CUDA {torch.version.cuda}")else:print("No GPU detected. In Colab: Runtime > Change runtime type > GPU, then run again.")
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0.0/82.7 kB ? eta -:--:--
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 82.7/82.7 kB 3.1 MB/s eta 0:00:00
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.2/3.2 MB 52.8 MB/s eta 0:00:00
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 425.6/425.6 kB 21.6 MB/s eta 0:00:00
GPU: Tesla T4, 14 GB, compute 7.5, CUDA 12.8
2 The sequences
These ASVs come from the same ZymoBIOMICS standard sequenced over the complete 16S gene, from the public SRA run SRR38028391. A single genome carries several slightly different copies of the gene, which full-length sequencing resolves, so there are more ASVs than species. The Appendix shows how they were produced.
The reads span the full-length gene, so the full-length checkpoint is used. Applying the V3-V4 checkpoint here would be an off-region use and would lower accuracy.
!deeptaxa predict --fasta-file asvs.fasta --checkpoint deeptaxa-full-length-v2.pt --output-dir out --tabularpred = pd.read_csv("out/asvs_deeptaxa_predictions.tsv", sep="\t").set_index("sequence_id")counts = counts.reindex(pred.index) # align read counts to the classified ASVsprint("mean confidence: genus", round(pred["genus_raw_score"].mean(), 2),"species", round(pred["species_raw_score"].mean(), 2))
2026-06-27 08:58:25,721 - INFO -
======================================================================
DeepTaxa Prediction Session (v1.1.0)
--------------------------------------------------
Started: 2026-06-27T08:58:25.721255
======================================================================
Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.
2026-06-27 08:58:26,545 - WARNING - Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads.
config.json: 100% 904/904 [00:00<00:00, 4.33MB/s]
configuration_bert.py: 100% 1.01k/1.01k [00:00<00:00, 3.71MB/s]
[transformers] A new version of the following files was downloaded from https://huggingface.co/zhihan1996/DNABERT-2-117M:
- configuration_bert.py
. Make sure to double-check they do not contain any added malicious code. To avoid downloading new versions of the code file, you can pin a revision.
tokenizer_config.json: 100% 158/158 [00:00<00:00, 710kB/s]
tokenizer.json: 100% 168k/168k [00:00<00:00, 86.2MB/s]
2026-06-27 08:58:28,389 - INFO - Initialized HybridCNNBERTClassifier with CNN: {'embed_dim': 896, 'num_filters': 256, 'kernel_sizes': [3, 5, 7], 'num_conv_layers': 1, 'dropout_prob': 0.2}, BERT hidden_size=896, output_attentions=False
2026-06-27 08:58:28,538 - INFO - Model loaded from checkpoint: deeptaxa-full-length-v2.pt with type: hybridcnnbert
2026-06-27 08:58:29,164 - INFO - Loaded 29 sequences from asvs.fasta
Predicting: 100% 1/1 [00:02<00:00, 2.22s/it]
2026-06-27 08:58:31,389 - INFO - Saved run UUID to out/deeptaxa_uuid.txt
2026-06-27 08:58:31,390 - INFO -
======================================================================
DeepTaxa Prediction Summary (v1.1.0)
--------------------------------------------------
Here's a summary of your prediction results:
- Total Sequences Processed: 29
- Prediction Time: 5.67 seconds
- Completed At: 2026-06-27T08:58:31.389506
======================================================================
2026-06-27 08:58:31,390 - INFO - Performance Metrics by Taxonomic Rank:
2026-06-27 08:58:31,390 - INFO - Rank | Mean Score | Std Score | Accuracy | Top-{top_k} Acc | F1 | Precision | Recall | AUC
2026-06-27 08:58:31,390 - INFO - ---------------------------------------------------------------------------------------------------------------------------------
2026-06-27 08:58:31,391 - INFO - domain | 1.0000 | 0.0000 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,391 - INFO - phylum | 1.0000 | 0.0000 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,391 - INFO - class | 1.0000 | 0.0000 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,391 - INFO - order | 1.0000 | 0.0000 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,391 - INFO - family | 1.0000 | 0.0000 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,391 - INFO - genus | 0.9929 | 0.0377 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,392 - INFO - species | 0.9693 | 0.0683 | N/A | N/A | N/A | N/A | N/A | N/A
2026-06-27 08:58:31,718 - INFO - Saved prediction results to: out/asvs_deeptaxa_predictions.json
2026-06-27 08:58:31,744 - INFO - Saved tabular prediction results to: out/asvs_deeptaxa_predictions.tsv
2026-06-27 08:58:31,744 - INFO -
======================================================================
Thank you for using DeepTaxa 🤗
======================================================================
mean confidence: genus 0.99 species 0.97
On full-length input the confidence is high at every rank, including species. This is the opposite of what the same model produces on short fragments, and it shows that the score reflects how much information the input carries.
5 Validate against the known genera
As in the V3-V4 tutorial, GTDB names are reduced to plain genus names so they can be compared with the NCBI names of the standard, and a reference result is loaded for cross-checking: DADA2 with the SILVA v138 database, labeled DADA2 + SILVA below. SILVA is the reference database; DADA2 is the classifier, using a naive Bayes model for the genus and exact matching for the species.
import resilva = pd.read_csv(f"{base}/fulllength_silva.tsv", sep="\t").set_index("ASV").reindex(pred.index)def base_genus(name):ifnotisinstance(name, str): # missing genus (NaN)returnNone name = re.sub(r"[ _-].*", "", name).lower() # drop GTDB suffixes and "sensu stricto"return {"limosilactobacillus": "lactobacillus", "shigella": "escherichia"}.get(name, name)EXPECTED = {"pseudomonas", "escherichia", "salmonella", "lactobacillus","enterococcus", "staphylococcus", "listeria", "bacillus"}dt_genus = pred["genus_predicted"].map(base_genus)sv_genus = silva["Genus"].map(base_genus)print("DeepTaxa recovered", len(set(dt_genus) & EXPECTED), "of 8 genera")print("DADA2 + SILVA recovered", len(set(sv_genus.dropna()) & EXPECTED), "of 8 genera")print("They agree on the genus of",round(counts[dt_genus == sv_genus].sum() / counts.sum() *100), "% of reads")
DeepTaxa recovered 8 of 8 genera
DADA2 + SILVA recovered 8 of 8 genera
They agree on the genus of 100 % of reads
6 Species: the main advantage of full-length data
The table lists the species calls for the most abundant ASVs; a single-word entry is a genus only, where the method stopped, and a two-word entry is a species. From the full-length gene DeepTaxa assigns a species to most ASVs, while DADA2 + SILVA assigns a species to a much smaller share and otherwise stops at the genus. The reference step is exact matching, which assigns a species only on an exact, unambiguous reference match, so its genus-only entries are reads it declined to name rather than reads it named incorrectly, and every species it does assign is correct. DeepTaxa still stops at the genus on a few ASVs, such as the most abundant Staphylococcus, but it resolves a species far more often than the reference. Where it names a species, the call is almost always a close relative of the expected organism, for example a member of the Bacillus subtilis group or Shigella for Escherichia coli, rather than an unrelated error. The confidence scores support this: full-length input enables DeepTaxa to assign a species to far more reads than either a short region or the exact-matching reference allows. The reference is exactly correct whenever it commits, and on a few ASVs, such as the Salmonella here, it resolves the species that DeepTaxa misses, so the gain is in coverage rather than uniform superiority.
The calls reduce to a single set of numbers: the share of reads reaching the correct species. DADA2 + SILVA is credited for exact matches only; DeepTaxa is credited for exact matches, and separately for exact matches plus close relatives that 16S cannot separate from the expected organism.
Reads correctly identified to species (%):
DADA2 + SILVA, exact: 32
DeepTaxa, exact: 35
DeepTaxa, exact or close relative: 66
7 Summary
On full-length sequences DeepTaxa recovered all eight genera, agreed with the reference method at the genus rank, and assigned a species to most ASVs with high confidence, stopping at the genus only where the marker does not separate the organisms. Its non-exact species calls are close relatives that 16S cannot resolve, so species labels remain constrained by the limited resolution of the marker at that rank, but the coverage is far greater than an exact-matching reference method provides. The practical recommendation is to classify full-length reads with the matching checkpoint.
8 Appendix: how the ASVs were made
The ASVs were produced with the DADA2 workflow for PacBio circular consensus reads.
