Add V4 (515F/806R) checkpoint: model weights, config variant, and model card

README.md

@@ -9,6 +9,7 @@ tags:
   - 16s-rrna
   - full-length-16s
   - v3-v4-amplicon
+  - v4-amplicon
   - illumina
 datasets:
   - systems-genomics-lab/greengenes
@@ -90,13 +91,47 @@ model-index:
           - type: f1
             value: 0.8592
             name: Species F1 (weighted)
+  - name: "DeepTaxa Hybrid CNN-BERT: V4 Amplicon (v1)"
+    results:
+      - task:
+          type: classification
+          name: Hierarchical Taxonomy Classification
+        dataset:
+          type: systems-genomics-lab/greengenes
+          name: Greengenes2 (2024-09, in-silico V4 extractions)
+          split: test
+        metrics:
+          - type: accuracy
+            value: 0.9998
+            name: Domain Accuracy
+          - type: accuracy
+            value: 0.9959
+            name: Phylum Accuracy
+          - type: accuracy
+            value: 0.9954
+            name: Class Accuracy
+          - type: accuracy
+            value: 0.9877
+            name: Order Accuracy
+          - type: accuracy
+            value: 0.9810
+            name: Family Accuracy
+          - type: accuracy
+            value: 0.9346
+            name: Genus Accuracy
+          - type: accuracy
+            value: 0.8284
+            name: Species Accuracy
+          - type: f1
+            value: 0.8016
+            name: Species F1 (weighted)
 ---
 
 # DeepTaxa: Hierarchical 16S rRNA Taxonomy Classification
 
 DeepTaxa is a deep learning model for hierarchical taxonomy classification of 16S rRNA gene sequences. The architecture couples a convolutional branch, which captures local k-mer motifs, with a BERT-style transformer, which captures long-range context. Both branches operate over tokens produced by the [DNABERT-2](https://huggingface.co/zhihan1996/DNABERT-2-117M) byte-pair encoder. Predictions are generated jointly for all seven standard taxonomic ranks: domain, phylum, class, order, family, genus, and species.
 
-Two checkpoints are released here: one trained on full-length 16S sequences and one trained on V3-V4 amplicons.
+Three checkpoints are released here: one trained on full-length 16S sequences, one trained on V3-V4 amplicons, and one trained on the shorter V4 amplicon.
 
 ## Checkpoint selection
 
@@ -104,6 +139,7 @@ Two checkpoints are released here: one trained on full-length 16S sequences and
 |---|---|---|
 | Sanger 27F/1492R, PacBio HiFi 16S, Oxford Nanopore long-read 16S, full-length reference lookup | Full-length v1 | `deeptaxa-full-length-v1.pt` |
 | Illumina paired-end V3-V4 with 341F/805R primers | V3-V4 v1 | `deeptaxa-v3v4-v1.pt` |
+| Illumina paired-end V4 with 515F/806R primers | V4 v1 | `deeptaxa-v4-v1.pt` |
 
 ## Released checkpoints
 
@@ -111,63 +147,64 @@ Two checkpoints are released here: one trained on full-length 16S sequences and
 |---|---|---:|---:|---:|---:|
 | Full-length v1 | 277,336 full-length 16S sequences (approximately 1,500 bp) from [Greengenes2](https://greengenes2.ucsd.edu/) | 92.88% | 92.03% | 0.0251 | 76.4 M |
 | V3-V4 v1 | 273,003 in-silico V3-V4 extractions (approximately 420 bp) from Greengenes2 | 87.55% | 85.92% | 0.0278 | 75.8 M |
+| V4 v1 | 274,509 in-silico V4 extractions (approximately 253 bp) from Greengenes2 | 82.84% | 80.16% | 0.0256 | 76.4 M |
 
-Species-level metrics above are single-seed (seed 42) test-set values for the published checkpoints. Across three seeds (42, 123, 456) the full-length checkpoint achieves species accuracy of 92.96% +/- 0.07 pp and species F1 of 92.12% +/- 0.08 pp, indicating high reproducibility.
+Species-level metrics above are single-seed (seed 42) test-set values for the published checkpoints. Across three seeds (42, 123, 456) the full-length checkpoint achieves species accuracy of 92.96% +/- 0.07 pp and species F1 of 92.12% +/- 0.08 pp, indicating high reproducibility. The V3-V4 and V4 checkpoints are released as single-seed (seed 42) models.
 
-Both checkpoints are inference-only. Optimizer and scheduler state have been removed to reduce file size; resuming training from these checkpoints is not supported.
+All three checkpoints are inference-only. Optimizer and scheduler state have been removed to reduce file size; resuming training from these checkpoints is not supported.
 
 ## Architecture
 
-The full-length and V3-V4 checkpoints share the canonical SMALL HybridCNNBERT configuration. Both were updated in April 2026 to this smaller, faster architecture: the full-length checkpoint matched or beat its prior numbers at every taxonomic rank with roughly 32% fewer parameters; the V3-V4 checkpoint achieved equivalent species-level performance (Acc 87.55% vs 87.52%, F1 85.92% vs 85.79%) at roughly 24% fewer parameters.
-
-| Component | Full-length v1 | V3-V4 v1 |
-|---|---|---|
-| `tokenizer_name` | `zhihan1996/DNABERT-2-117M` | `zhihan1996/DNABERT-2-117M` |
-| `max_length` | 512 (tokens) | 512 (tokens) |
-| `embed_dim` | 896 | 896 |
-| `num_filters` | 256 | 256 |
-| `kernel_sizes` | `[3, 5, 7]` | `[3, 5, 7]` |
-| `num_conv_layers` | 1 | 1 |
-| `hidden_size` | 896 | 896 |
-| `num_hidden_layers` | 4 | 4 |
-| `num_attention_heads` | 7 | 7 |
-| `intermediate_size` | 3584 | 3584 |
-| `hidden_dropout_prob` | 0.20 | 0.20 |
+The full-length, V3-V4, and V4 checkpoints share the canonical compact HybridCNNBERT configuration. The full-length and V3-V4 checkpoints were updated in April 2026 to this smaller, faster architecture: the full-length checkpoint matched or beat its prior numbers at every taxonomic rank with roughly 32% fewer parameters; the V3-V4 checkpoint achieved equivalent species-level performance (Acc 87.55% vs 87.52%, F1 85.92% vs 85.79%) at roughly 24% fewer parameters. The V4 checkpoint (added June 2026) was trained from scratch in this same configuration on in-silico V4 amplicons.
+
+| Component | Full-length v1 | V3-V4 v1 | V4 v1 |
+|---|---|---|---|
+| `tokenizer_name` | `zhihan1996/DNABERT-2-117M` | `zhihan1996/DNABERT-2-117M` | `zhihan1996/DNABERT-2-117M` |
+| `max_length` | 512 (tokens) | 512 (tokens) | 512 (tokens) |
+| `embed_dim` | 896 | 896 | 896 |
+| `num_filters` | 256 | 256 | 256 |
+| `kernel_sizes` | `[3, 5, 7]` | `[3, 5, 7]` | `[3, 5, 7]` |
+| `num_conv_layers` | 1 | 1 | 1 |
+| `hidden_size` | 896 | 896 | 896 |
+| `num_hidden_layers` | 4 | 4 | 4 |
+| `num_attention_heads` | 7 | 7 | 7 |
+| `intermediate_size` | 3584 | 3584 | 3584 |
+| `hidden_dropout_prob` | 0.20 | 0.20 | 0.20 |
 
 ## Test-set performance
 
-Both checkpoints were evaluated on their respective held-out Greengenes2 2024.09 test splits. Numbers below are seed 42 test-set values for the published checkpoints.
+All three checkpoints were evaluated on their respective held-out Greengenes2 2024.09 test splits. Numbers below are seed 42 test-set values for the published checkpoints.
 
-| Rank    | Full-length Acc | Full-length F1 | V3-V4 Acc | V3-V4 F1 |
-|---------|---------------:|---------------:|----------:|---------:|
-| Domain  |         99.99% |         99.99% |    99.99% |    99.99% |
-| Phylum  |         99.68% |         99.67% |    99.68% |    99.66% |
-| Class   |         99.63% |         99.59% |    99.64% |    99.60% |
-| Order   |         99.09% |         98.99% |    98.99% |    98.88% |
-| Family  |         98.61% |         98.41% |    98.41% |    98.19% |
-| Genus   |         96.93% |         96.51% |    95.27% |    94.73% |
-| Species |         92.88% |         92.03% |    87.55% |   85.92% |
+| Rank    | Full-length Acc | Full-length F1 | V3-V4 Acc | V3-V4 F1 | V4 Acc | V4 F1 |
+|---------|---------------:|---------------:|----------:|---------:|-------:|------:|
+| Domain  |         99.99% |         99.99% |    99.99% |    99.99% | 99.98% | 99.98% |
+| Phylum  |         99.68% |         99.67% |    99.68% |    99.66% | 99.59% | 99.57% |
+| Class   |         99.63% |         99.59% |    99.64% |    99.60% | 99.54% | 99.49% |
+| Order   |         99.09% |         98.99% |    98.99% |    98.88% | 98.77% | 98.67% |
+| Family  |         98.61% |         98.41% |    98.41% |    98.19% | 98.10% | 97.88% |
+| Genus   |         96.93% |         96.51% |    95.27% |    94.73% | 93.46% | 92.65% |
+| Species |         92.88% |         92.03% |    87.55% |   85.92% | 82.84% | 80.16% |
 
 
 ## Training configuration
 
-| Parameter | Full-length v1 | V3-V4 v1 |
-|---|---|---|
-| Training data | Greengenes2 2024.09 training set (277,336 full-length sequences, approximately 1,500 bp) | In-silico V3-V4 extractions from the same training set (273,003 amplicons) |
-| Test data | Greengenes2 2024.09 test split (69,335 full-length sequences) | V3-V4 extractions from the test split (68,282 amplicons) |
-| Extraction primers | N/A | 341F `CCTACGGGNGGCWGCAG` and 805R `GACTACHVGGGTATCTAATCC` |
-| Label space (species) | 16,909 | 8,347 |
-| Label space (domain / phylum / class / order / family / genus) | 2 / 129 / 349 / 997 / 2,250 / 7,287 | 2 / 115 / 270 / 709 / 1,528 / 4,529 |
-| Total parameters | 76,365,205 | 75,813,550 |
-| Learning rate | 5e-4 | 5e-4 |
-| Batch size | 64 | 64 |
-| Weight decay | 1e-2 | 1e-2 |
-| Epochs | 10 | 10 |
-| Loss | Cross-entropy with uniform per-rank weights | Cross-entropy with uniform per-rank weights |
-| Optimizer | AdamW (beta1 = 0.9, beta2 = 0.999) | AdamW (beta1 = 0.9, beta2 = 0.999) |
-| Learning rate schedule | Linear warm-up over 10% of steps, followed by linear decay | Linear warm-up over 10% of steps, followed by linear decay |
-| Seed | 42 | 42 |
-| Hardware | NVIDIA GeForce RTX 4090 | NVIDIA GeForce RTX 4090 |
+| Parameter | Full-length v1 | V3-V4 v1 | V4 v1 |
+|---|---|---|---|
+| Training data | Greengenes2 2024.09 training set (277,336 full-length sequences, approximately 1,500 bp) | In-silico V3-V4 extractions from the same training set (273,003 amplicons) | In-silico V4 extractions from the same training set (274,509 amplicons) |
+| Test data | Greengenes2 2024.09 test split (69,335 full-length sequences) | V3-V4 extractions from the test split (68,282 amplicons) | V4 extractions from the test split (68,668 amplicons) |
+| Extraction primers | N/A | 341F `CCTACGGGNGGCWGCAG` and 805R `GACTACHVGGGTATCTAATCC` | 515F `GTGYCAGCMGCCGCGGTAA` and 806R `GGACTACNVGGGTWTCTAAT` |
+| Label space (species) | 16,909 | 8,347 | 16,909 |
+| Label space (domain / phylum / class / order / family / genus) | 2 / 129 / 349 / 997 / 2,250 / 7,287 | 2 / 115 / 270 / 709 / 1,528 / 4,529 | 2 / 129 / 349 / 997 / 2,250 / 7,287 |
+| Total parameters | 76,365,205 | 75,813,550 | 76,365,205 |
+| Learning rate | 5e-4 | 5e-4 | 5e-4 |
+| Batch size | 64 | 64 | 64 |
+| Weight decay | 1e-2 | 1e-2 | 1e-2 |
+| Epochs | 10 | 10 | 10 |
+| Loss | Cross-entropy with uniform per-rank weights | Cross-entropy with uniform per-rank weights | Cross-entropy with uniform per-rank weights |
+| Optimizer | AdamW (beta1 = 0.9, beta2 = 0.999) | AdamW (beta1 = 0.9, beta2 = 0.999) | AdamW (beta1 = 0.9, beta2 = 0.999) |
+| Learning rate schedule | Linear warm-up over 10% of steps, followed by linear decay | Linear warm-up over 10% of steps, followed by linear decay | Linear warm-up over 10% of steps, followed by linear decay |
+| Seed | 42 | 42 | 42 |
+| Hardware | NVIDIA GeForce RTX 4090 | NVIDIA GeForce RTX 4090 | NVIDIA A40 |
 
 ## Usage
 
@@ -180,6 +217,9 @@ wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-
 # V3-V4 checkpoint
 wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-v3v4-v1.pt
 
+# V4 checkpoint
+wget https://huggingface.co/systems-genomics-lab/deeptaxa/resolve/main/deeptaxa-v4-v1.pt
+
 # Or clone the full repository
 git clone https://huggingface.co/systems-genomics-lab/deeptaxa
 ```
@@ -200,6 +240,12 @@ v3v4_ckpt = hf_hub_download(
     repo_id="systems-genomics-lab/deeptaxa",
     filename="deeptaxa-v3v4-v1.pt",
 )
+
+# V4
+v4_ckpt = hf_hub_download(
+    repo_id="systems-genomics-lab/deeptaxa",
+    filename="deeptaxa-v4-v1.pt",
+)
 ```
 
 ### Install DeepTaxa and run predictions
@@ -218,9 +264,15 @@ deeptaxa predict \
   --fasta-file your_v3v4_amplicons.fna.gz \
   --checkpoint deeptaxa-v3v4-v1.pt \
   --output-dir predictions/
+
+# V4 amplicons (Illumina, already demultiplexed and primer-trimmed)
+deeptaxa predict \
+  --fasta-file your_v4_amplicons.fna.gz \
+  --checkpoint deeptaxa-v4-v1.pt \
+  --output-dir predictions/
 ```
 
-Input preparation for V3-V4 amplicons: the input FASTA file should contain V3-V4 sequences that have already been demultiplexed and primer-trimmed by an upstream tool such as [DADA2](https://benjjneb.github.io/dada2/), [cutadapt](https://cutadapt.readthedocs.io/), or [QIIME2](https://qiime2.org/). The V3-V4 checkpoint was trained on in-silico primer extractions, which approximate merged paired-end amplicons. Paired-end reads should therefore be merged into consensus amplicons prior to prediction, or the forward read alone may be provided.
+Input preparation for amplicon checkpoints: the input FASTA file should contain region-matched sequences that have already been demultiplexed and primer-trimmed by an upstream tool such as [DADA2](https://benjjneb.github.io/dada2/), [cutadapt](https://cutadapt.readthedocs.io/), or [QIIME2](https://qiime2.org/). The V3-V4 and V4 checkpoints were trained on in-silico primer extractions (341F/805R and 515F/806R respectively), which approximate merged paired-end amplicons. Paired-end reads should therefore be merged into consensus amplicons prior to prediction, or the forward read alone may be provided.
 
 Full usage documentation and analysis notebooks are available in the [GitHub repository](https://github.com/systems-genomics-lab/deeptaxa).
 
@@ -243,6 +295,13 @@ Limitations specific to the V3-V4 checkpoint:
 - The label space contains 8,347 species. Those for which no V3-V4 amplicon could be extracted during training are absent and cannot be predicted.
 - Primer specificity: the model was trained on 341F/805R extractions. Sequences amplified with other V3-V4 primers, such as 357F or 338F, or with substantially different region boundaries may yield degraded predictions.
 
+Limitations specific to the V4 checkpoint:
+
+- Species-level accuracy is approximately 82.8%. The approximately 253 bp V4 region carries less taxonomic information than V3-V4 or the full 16S gene, so species-level calls should be read together with their confidence scores.
+- The label space contains 16,909 species (the same as the full-length checkpoint), retained because V4 amplicons were extracted at 99.0% yield. Species for which no V4 amplicon could be extracted during training are absent and cannot be predicted.
+- Primer specificity: the model was trained on 515F/806R extractions. Sequences amplified with other V4 primers or with substantially different region boundaries may yield degraded predictions.
+- The V4 checkpoint is released as a single-seed (seed 42) model; no cross-seed standard deviation is reported for it.
+
 ## Citation
 
 ```bibtex
@@ -277,4 +336,6 @@ For support, please open an issue on the [GitHub repository](https://github.com/
 
 ## Version history
 
+v1 (June 2026). Added the V4 checkpoint (`deeptaxa-v4-v1.pt`), trained from scratch in the canonical compact HybridCNNBERT configuration on 274,509 in-silico V4 extractions (515F/806R, approximately 253 bp) from Greengenes2 2024.09. Single-seed (seed 42); species accuracy 82.84%, F1 80.16%, ECE 0.0256. The V4 amplicon was extracted at 99.0% yield, so the checkpoint keeps the full 16,909-species label space and matches the full-length parameter count (76.4 M).
+
 v1 (April 2026). Initial release of the full-length and V3-V4 checkpoints. Both were updated in late April 2026 to the canonical SMALL HybridCNNBERT architecture (76.4 M and 75.8 M parameters respectively; kernels 3/5/7, 256 filters, 4 transformer layers, 7 attention heads, 3584 FFN intermediate, 896 hidden, dropout 0.20). The full-length update (v1.1) matched or beat the prior full-length numbers at every taxonomic rank with roughly 32% fewer parameters and roughly half the training time. The V3-V4 update (v1.2) achieved equivalent species-level performance (Acc 87.55% vs 87.52%, F1 85.92% vs 85.79%) at roughly 24% fewer parameters, harmonizing the two checkpoints under the same architecture. Users who downloaded either checkpoint before the corresponding update may see different SHA-256 hashes; re-downloading retrieves the updated file.

config.json

@@ -283,6 +283,120 @@
                 }
             },
             "derived_from": "Canonical SMALL HybridCNNBERT hyperparameters (matching the full-length v1.1 release), applied from scratch to in-silico V3-V4 extractions from Greengenes2 2024.09. Updated in v1.2 in place over the prior LARGE Optuna v3v4 release: under identical evaluation the SMALL configuration achieves equivalent species-level performance (seed-42 Acc 87.55 vs 87.52, F1 85.92 vs 85.79) at roughly 24 percent fewer parameters."
+        },
+        "v4": {
+            "checkpoint_file": "deeptaxa-v4-v1.pt",
+            "architecture": {
+                "max_length": 512,
+                "embed_dim": 896,
+                "num_filters": 256,
+                "kernel_sizes": [
+                    3,
+                    5,
+                    7
+                ],
+                "num_conv_layers": 1,
+                "hidden_size": 896,
+                "num_hidden_layers": 4,
+                "num_attention_heads": 7,
+                "intermediate_size": 3584,
+                "hidden_dropout_prob": 0.2
+            },
+            "training_hyperparameters": {
+                "learning_rate": 0.0005,
+                "batch_size": 64,
+                "epochs": 10,
+                "loss_function": "cross_entropy",
+                "level_weights": [
+                    1.0,
+                    1.0,
+                    1.0,
+                    1.0,
+                    1.0,
+                    1.0,
+                    1.0
+                ],
+                "optimizer": "AdamW",
+                "optimizer_params": {
+                    "lr": 0.0005,
+                    "betas": [
+                        0.9,
+                        0.999
+                    ],
+                    "weight_decay": 0.01
+                },
+                "scheduler_warmup_ratio": 0.1,
+                "seed": 42
+            },
+            "total_parameters": 76365205,
+            "training_date": "2026-06-28",
+            "training_hardware": "NVIDIA A40",
+            "training_dataset": {
+                "name": "Greengenes2 2024.09 (in-silico V4 extractions)",
+                "train_amplicons": 274509,
+                "test_amplicons": 68668,
+                "extraction_yield_train": 0.99,
+                "extraction_yield_test": 0.99,
+                "forward_primer": "GTGYCAGCMGCCGCGGTAA",
+                "reverse_primer": "GGACTACNVGGGTWTCTAAT",
+                "primer_name_forward": "515F",
+                "primer_name_reverse": "806R",
+                "max_primer_mismatches": 2,
+                "amplicon_length_median_bp": 253,
+                "amplicon_length_mean_bp": 253,
+                "amplicon_length_range_bp": [
+                    76,
+                    1669
+                ]
+            },
+            "taxonomic_levels": {
+                "domain": 2,
+                "phylum": 129,
+                "class": 349,
+                "order": 997,
+                "family": 2250,
+                "genus": 7287,
+                "species": 16909
+            },
+            "test_metrics": {
+                "_note": "Single-seed test-set metrics for the published checkpoint (seed 42).",
+                "domain": {
+                    "accuracy": 0.9998,
+                    "f1_score": 0.9998,
+                    "ece": 0.0002
+                },
+                "phylum": {
+                    "accuracy": 0.9959,
+                    "f1_score": 0.9957,
+                    "ece": 0.0025
+                },
+                "class": {
+                    "accuracy": 0.9954,
+                    "f1_score": 0.9949,
+                    "ece": 0.0024
+                },
+                "order": {
+                    "accuracy": 0.9877,
+                    "f1_score": 0.9867,
+                    "ece": 0.0058
+                },
+                "family": {
+                    "accuracy": 0.981,
+                    "f1_score": 0.9788,
+                    "ece": 0.0076
+                },
+                "genus": {
+                    "accuracy": 0.9346,
+                    "f1_score": 0.9265,
+                    "ece": 0.0172
+                },
+                "species": {
+                    "accuracy": 0.8284,
+                    "f1_score": 0.8016,
+                    "ece": 0.0256
+                }
+            },
+            "derived_from": "Canonical compact HybridCNNBERT hyperparameters (matching the full-length v1 release), applied from scratch to in-silico V4 extractions from Greengenes2 2024.09. The approximately 253 bp V4 amplicon (515F/806R) was extracted at 99.0 percent yield, which retains the full 16,909-species vocabulary, so the checkpoint matches the full-length parameter count (76.4 M)."
         }
     }
-}
+}

deeptaxa-v4-v1.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:193d802bc7e0297da794a0c480d63770c1f06af60bcedf3a800419e2046767f3
+size 306429554