Metadata-Version: 2.4
Name: Mpox-Trinet
Version: 0.9.0
Summary: Tri-Net v2 — reproducible deep-learning framework for Mpox skin-lesion diagnosis
Author: Sudharsan S
License: MIT License
        
        Copyright (c) 2026 Sudharsan S
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis
Project-URL: Repository, https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis
Keywords: deep-learning,medical-imaging,monkeypox,mpox,dermatology,ensemble
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tensorflow==2.16.2
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas==2.2.2
Requires-Dist: scikit-learn==1.5.1
Requires-Dist: scipy==1.13.1
Requires-Dist: pyswarms==1.3.0
Requires-Dist: xgboost==2.1.1
Requires-Dist: pillow==10.4.0
Requires-Dist: opencv-python==4.10.0.84
Requires-Dist: matplotlib==3.9.2
Requires-Dist: seaborn==0.13.2
Requires-Dist: joblib==1.4.2
Requires-Dist: tqdm==4.66.5
Requires-Dist: kaggle==2.2.3
Requires-Dist: typer>=0.12
Requires-Dist: pyyaml>=6.0
Provides-Extra: metal
Requires-Dist: tensorflow-metal==1.1.0; extra == "metal"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="assets/mpox_logo.png" width="270" alt="MPOX">

## Tri-Net v2

### A Reproducible Deep-Learning Framework for Multi-Class Skin-Lesion and Symptom-Based Monkeypox (Mpox) Diagnosis

*Official implementation of the Tri-Net study — upgraded with modern backbones, learned feature fusion, and a fully reproducible evaluation framework.*

[![tests](https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis/actions/workflows/tests.yml/badge.svg)](https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis/actions/workflows/tests.yml)
[![lint](https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis/actions/workflows/lint.yml/badge.svg)](https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis/actions/workflows/lint.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![TensorFlow](https://img.shields.io/badge/TensorFlow-2.16-orange)](https://www.tensorflow.org/)
[![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)](docker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Code style: ruff](https://img.shields.io/badge/lint-ruff-purple)](https://github.com/astral-sh/ruff)
[![Reproducible](https://img.shields.io/badge/results-100%25%20reproducible-brightgreen)](docs/reproducibility.md)
[![Peer Review](https://img.shields.io/badge/peer%20review-Scientific%20Reports%20(under%20revision)-yellow)](#original-publication)

**[Original Publication](#original-publication) • [Abstract](#abstract) • [What's New in v2](#whats-new-in-v2) • [Results](#results) • [Integrity Audit](#reproducibility--integrity-audit) • [Quick Start](#quick-start) • [Model Zoo](#model-zoo) • [Docs](#documentation) • [Citation](#citation)**

</div>

<br>

<div align="center">
<img src="assets/confusion_matrix.png" width="560" alt="14-class confusion matrix">
<p><sub>14-class confusion matrix — leakage-free split, real test set, regenerated by <code>trinet evaluate --champion</code></sub></p>
</div>

<br>

## Original Publication

> **Tri-Net: Unified Deep Learning for Skin Lesion and Symptom-Based Monkeypox Detection**
> Sudharsan S¹ · Prabu Selvam²ᵗ · Nirmala Veeramani³ᵗ · Kiran Kumar B⁴ · Nikola Ivković⁵ · Korhan Cengiz⁶,⁷
> ¹²⁴ School of Computing, SRM Institute of Engineering and Technology, Tiruchirappalli Campus, India · ³ School of Computing, SASTRA Deemed University, India · ⁵ Faculty of Organization and Informatics, University of Zagreb, Croatia · ⁶ College of Computing and Intelligent Systems, University of Khorfakkan, UAE · ⁷ Department of Electrical Engineering, Biruni University, Istanbul
> ᵗ Corresponding authors

**Status:** currently under peer review at ***Scientific Reports*** (Springer Nature, Nature Portfolio). Both reviewers have recommended the manuscript for acceptance; outstanding editorial requirements are (a) a formal **Code Availability** statement pointing to a DOI-assigning archive of this repository, and (b) provenance/permission documentation for a small number of figures. This repository is the code artifact referenced by that statement — see [Code Availability](#code-availability) below.

This repo is not the paper's original codebase — that codebase was, at the time this framework was built, largely unimplemented against the paper's own claims (see the [Integrity Audit](#reproducibility--integrity-audit)). **Tri-Net v2** is a from-scratch, tested, reproducible rebuild that keeps the paper's core idea — a Tri-Net ensemble plus a symptom-based classifier — and makes every number in it independently verifiable. The original scripts are preserved unmodified under [`archive/`](archive/) for provenance and direct comparison.

## Abstract

The 2022–2024 re-emergence of Monkeypox (Mpox) renewed interest in rapid, non-invasive computer-aided diagnosis. **Tri-Net** proposes a unified deep-learning approach that couples skin-lesion image analysis with symptom-based prediction. **Tri-Net v2** re-engineers the study into an installable, tested, and fully reproducible framework and modernises it end to end. It evaluates a challenging **14-class** dermatological setting under a strictly **leakage-free** train/validation/test split, benchmarks five convolutional backbones (including current-generation **ConvNeXt** and **EfficientNetV2**) as frozen feature extractors, and introduces a **learned feature-fusion** ablation across five strategies (mean, PSO-weighted, concatenation-MLP, gated attention, transformer encoder). The best configuration attains **77.2% top-1 accuracy** and **97.0% macro-AUC** on the fine-grained 14-class task, while the clinically-actionable **binary Mpox-vs-rest** screening formulation reaches **98.4% accuracy** and **99.6% AUC** with reported sensitivity, specificity, and Wilson confidence intervals. The framework ships a complete evaluation suite (5-fold cross-validation, McNemar's test, Cohen's κ, ensemble diversity, Grad-CAM), a unified CLI, CI, Docker, and a model zoo. Every figure and number is regenerated from code — nothing is hand-typed.

## What's New in v2

- **Modern backbones** — ConvNeXt-Tiny (the strongest single backbone, 69.3%) and EfficientNetV2-S added alongside the original EfficientNetB4 / InceptionResNetV2 / DenseNet201.
- **Learned feature fusion** — a five-way ablation (Mean, PSO, Concat-MLP, Gated-Attention, Transformer); feature-level fusion is the champion.
- **Rigorous 14-class benchmark** — a leakage-free 80/10/10 split (original images only) that never lets augmented copies straddle train/val/test — see [why this matters](#reproducibility--integrity-audit).
- **Dual-task evaluation** — fine-grained 14-class diagnosis reported separately from binary Mpox screening, each with appropriate metrics and confidence intervals.
- **Full reproducibility** — installable `trinet` package, unified CLI, unit tests, GitHub Actions CI, Docker, and a model zoo. Every number regenerates from committed code.
- **Complete evaluation suite** — confusion matrices, ROC, Cohen's κ, McNemar's test, 5-fold CV, ensemble diversity analysis, and Grad-CAM interpretability — none of which existed in the original repository.
- **Checkpoint integrity** — a save-time protocol verifies that serialized models reproduce identical logits across processes, so deployed weights behave exactly as evaluated.

## Results

| Task | Metric | Score |
|---|---|---|
| Binary **Mpox screening** (clinical task) | Accuracy / AUC | **98.35% / 99.58%** |
| 14-class fine-grained diagnosis | Accuracy | **77.23%** |

The 14-class result is on a demanding benchmark: 14 classes, leakage-free 80/10/10 split, ~3,000 real images, cross-validated — a substantially harder setting than the binary or low-cardinality tasks common in the Mpox imaging literature, and a smaller, non-inflated corpus compared to the original paper's split (see the audit below).

<details>
<summary><b>Headline progression (click to expand)</b></summary>

<br>

| Configuration | Test accuracy |
|---|---:|
| Baseline ensemble (three original backbones, Mean/PSO) | 72.60% |
| + ConvNeXt-Tiny backbone (Mean ensemble) | 75.25% |
| **+ Concat-MLP feature fusion (champion)** | **77.23%** |

Net gain from the v2 upgrades: **+4.63 points**. The ensemble's diversity-derived oracle ceiling is ~80%, so fusion captures most of the headroom available in this ensemble.

</details>

<details>
<summary><b>Single-backbone benchmark (frozen features)</b></summary>

<br>

| Backbone | Accuracy | Macro-F1 | AUC | κ |
|---|---:|---:|---:|---:|
| EfficientNetB4 | 58.4 | 63.3 | 95.0 | 54.2 |
| DenseNet201 | 66.3 | 67.2 | 95.6 | 62.8 |
| InceptionResNetV2 | 68.0 | 68.8 | 96.2 | 64.4 |
| **ConvNeXt-Tiny** | **69.3** | **70.3** | **96.5** | **65.9** |

</details>

<details>
<summary><b>Fusion-strategy ablation (best-3 backbones)</b></summary>

<br>

| Strategy | Learnable | Params | Accuracy | Macro-F1 | AUC | κ |
|---|---|---:|---:|---:|---:|---:|
| **Concat + MLP** | yes | 2.2 M | **77.2** | **79.1** | 97.0 | **74.6** |
| Mean | no | 0 | 75.3 | 77.2 | 97.1 | 72.5 |
| PSO | global | 3 | 73.3 | 74.7 | 96.8 | 70.4 |
| Transformer | yes | 1.5 M | 65.0 | 68.3 | 96.6 | 61.6 |
| Gated Attention | yes | 1.2 M | 63.4 | 63.2 | 95.6 | 59.8 |

Feature-level fusion beats probability fusion; the highest-capacity variants overfit at this dataset size.

</details>

<details>
<summary><b>Cross-validation, ensemble diversity & per-class</b></summary>

<br>

**5-fold CV** (mean ± SD): EfficientNetB4 59.0 ± 2.6 · InceptionResNetV2 59.2 ± 1.4 · DenseNet201 65.5 ± 0.6 · **Tri-Net 69.3 ± 0.8** (beats every base in all folds).

**Diversity**: pairwise disagreement 24.9%, Yule's Q 0.75, error-correlation ρ 0.43, double-fault 19.7% → variance reduction, oracle ceiling ≈ 80%.

**Per-class split**: pox/infectious classes **89.3%** vs dermoscopy (skin-cancer) classes **73.2%** — confusions concentrate on clinically hard pairs (Melanoma↔Nevus, BCC↔SCC).

</details>

<details>
<summary><b>Binary screening — full breakdown</b></summary>

<br>

| Metric | Score | 95% CI (Wilson) |
|---|---:|---|
| Accuracy | 98.4% | 96.2 – 99.3 |
| AUC | 99.6% | — |
| Sensitivity | 86.2% | 69.4 – 94.5 |
| Specificity | 99.6% | 98.0 – 99.9 |

Specificity is very high; sensitivity has a wider interval (few positive test cases). Threshold tuning toward sensitivity is a natural next step — see [`docs/benchmark.md`](docs/benchmark.md).

</details>

Full tables and ablations: **[`docs/benchmark.md`](docs/benchmark.md)**.

## Reproducibility & Integrity Audit

This is the core contribution of v2: a documented, evidence-based account of where the original paper's claims and its accompanying code diverged, verified directly against the manuscript and its original repository.

| # | Finding | Evidence |
|---|---|---|
| 1 | **The paper's PSO ensemble had no corresponding implementation in the original repository** — the code simply concatenated backbone features. We built a real PSO optimizer; under our reproduction it **underperforms** a plain probability mean (73.3% vs 75.3%). | Paper §3.4 & Algorithm 1 claim PSO weights `(0.42, 0.32, 0.26)`; original `lesion.py` contained no optimizer. |
| 2 | **No trained 14-class checkpoint was ever saved** in the original repository — the 97.86%/97.86%±0.29 figures reported across the paper's Tables 3, 6, 8, and 9 have no retrievable model artifact behind them. | Repository inspection at rebuild time. |
| 3 | **The paper is internally inconsistent about which module scored 97.86%.** The abstract attributes it to *"the symptom-based module alone,"* while the body's Tables 3, 6, 8, and 9 all report the same figure for the **image-based Tri-Net ensemble** instead. | Direct comparison of Abstract vs. §4.3–4.5. |
| 4 | **Two different confusion matrices for the same binary evaluation don't agree.** Fig. 6 reports TP=905, FN=16, FP=13, TN=431 (n=1,365); the accompanying paragraph reports TP=920, FN=12, FP=20, TN=445 (n=1,397) — different totals, different every cell. A third figure elsewhere (§4.4) describes 3,710 test images with 3,598 correct / 111 incorrect, which matches neither. | Paper Fig. 6 vs. the paragraph immediately following it vs. §4.4. |
| 5 | **Section 4 opens with a paragraph describing an unrelated study** — a routing/optimization paper about energy-aware networking — rather than the Mpox experiments actually being reported, a clear copy-paste artifact from a different manuscript. | Paper §4, opening paragraph. |
| 6 | **The claimed 97.86% is very likely inflated by augmentation leakage.** The paper's 14-class split totals 29,322 images (23,458 train / 2,932 val / 2,932 test) built by heavy augmentation of a much smaller base — MSLD ships pre-augmented copies, and augmenting *before* splitting lets near-duplicate images straddle train/val/test. Our leakage-free split (original images only, augmentation applied at train time only) totals **3,032 images** — roughly **1/10th the size** — and yields 77.23%, not 97.86%. | Paper §3.1 vs. `docs/datasets.md`. |
| 7 | **None of the paper's stated evaluation methodology existed in the original code** — 5-fold CV, McNemar's test, Cohen's κ, ROC/AUC, Grad-CAM. We built the full suite from scratch; see [`docs/benchmark.md`](docs/benchmark.md). | Repository inspection vs. paper §4.5–4.7. |
| 8 | **The symptom-based classifier's headline number relied on a leaking feature.** Dropping the `sum`/leakage-prone feature and retraining honestly yields **~64–70%** across CNN, Logistic Regression, Random Forest, and XGBoost — far from any 97%+ figure. | `docs/datasets.md`, `docs/benchmark.md`. |
| 9 | **Fine-tuning does not help at v2's data scale** — unfreezing backbone layers on ~2.4k images overfits immediately and matches the frozen-ensemble baseline, contradicting the assumption that more training freedom is strictly better. | `docs/benchmark.md`. |
| 10 | **Higher-capacity fusion (Transformer, gated attention) generalizes worse than simple Concat-MLP fusion** at this dataset size — a statement about the data regime, not the architectures. | Fusion ablation table above. |

None of this is a claim of bad faith — research code commonly lags a manuscript, and the reviewers' own comments note the revised manuscript now "adequately addresses" prior concerns. But reproducibility is the point of publishing quantitative results, and this repository exists to make every one of the numbers above independently checkable, permanently, from committed code. The original paper's scripts are preserved unmodified under [`archive/`](archive/) for anyone who wants to verify these findings directly.

## Methodology

**Backbones & transfer learning.** Five ImageNet-pretrained backbones are compared, each with its own required preprocessing. Each *frozen* backbone feeds a lightweight head (Dense→BatchNorm→Dense→Dropout→Softmax); features are cached once so training runs in seconds/epoch. Class imbalance is handled with balanced class weights.

**Fusion strategies.** Five ways to combine backbones on identical features: **Mean** (equal-weight probability average), **PSO** (a global weight vector optimised by Particle Swarm Optimization), **Concat-MLP** (concatenate features → MLP), **Gated Attention** (per-image attention over backbone tokens), and **Transformer** (self-attention encoder).

**Symptom module.** A compact CNN with Logistic-Regression / Random-Forest / XGBoost baselines on the structured symptom dataset, using a leakage-free feature pipeline.

**Evaluation protocol.** Accuracy, macro-P/R/F1, one-vs-rest macro-AUC, and Cohen's κ on the held-out test set; 5-fold CV on original features; McNemar's test; ensemble diversity; Grad-CAM; and Wilson CIs for binary screening. Full details: [`docs/architecture.md`](docs/architecture.md).

## Architecture

```
datasets ──► features ──► base heads ──► ensemble ─┐
 (download,   (frozen      (per-backbone   (PSO /   ├─► evaluation
  prepare)     backbone     classifier)     mean)   │    (metrics, confusion,
               cache)                               │     ROC, Kappa, McNemar,
                                    fusion ─────────┘     diversity, Grad-CAM)
                                 (Concat-MLP / attention / transformer)
```

Backbones are frozen and cached to disk as feature vectors, so head training runs in seconds per epoch rather than hours.

| Backbone | Pooled dim | Notes |
|---|---:|---|
| EfficientNetB4 | 1792 | Metal-compatible |
| InceptionResNetV2 | 1536 | Metal-compatible |
| DenseNet201 | 1920 | Metal-compatible |
| **ConvNeXt-Tiny** | 768 | best single backbone; CPU extraction on Apple Metal |
| EfficientNetV2-S | 1280 | CPU extraction on Apple Metal |

Full details: [`docs/architecture.md`](docs/architecture.md).

## Quick Start

```bash
git clone https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis.git
cd Synergistic-Deep-Learning-for-Monkeypox-Diagnosis
python -m venv .venv && source .venv/bin/activate
pip install -e .              # add ".[metal]" on Apple Silicon, ".[dev]" for tests/linting
```

Run the full pipeline:

```bash
trinet download        # fetch datasets (needs a Kaggle API token)
trinet prepare         # leakage-free 14-class split + clean symptom data
trinet features        # cache frozen-backbone features
trinet train           # train classification heads
trinet fusion          # fusion-strategy ablation (Concat-MLP is the champion)
trinet evaluate --champion   # figures + tables from the best model
```

Or the whole image pipeline in one shot: `trinet benchmark`. Full CLI reference: `trinet --help`.

**Inference on a single image:**

```bash
trinet predict lesion.jpg
```

```python
from trinet.inference.predict import predict_image
print(predict_image("lesion.jpg"))
```

**As a library:**

```python
from trinet.models.fusion import build_concat_mlp
from trinet.evaluation.metrics import compute_scores
```

## Model Zoo

| Model | Task | Accuracy | AUC | Weights |
|---|---|---:|---:|:--:|
| **Tri-Net v2 (Concat-MLP fusion)** | 14-class | **77.2** | 97.0 | ✅ |
| ConvNeXt-Tiny (single backbone) | 14-class | 69.3 | 96.5 | ✅ |
| Mean ensemble | 14-class | 75.3 | **97.1** | — |
| PSO ensemble | 14-class | 73.3 | 96.8 | ✅ |
| **Tri-Net v2 (Mpox screening)** | binary | **98.4** | **99.6** | ✅ |

Full breakdown, params, and Macro-F1 / Kappa per model: **[`docs/model_zoo.md`](docs/model_zoo.md)**. Pretrained weights are attached to the matching [GitHub Release](https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis/releases).

## Documentation

| Doc | Covers |
|---|---|
| [`docs/architecture.md`](docs/architecture.md) | Models, fusion strategies, full pipeline |
| [`docs/model_zoo.md`](docs/model_zoo.md) | Pretrained models, weights, usage |
| [`docs/datasets.md`](docs/datasets.md) | Data sources, licensing, 14-class composition |
| [`docs/benchmark.md`](docs/benchmark.md) | Full results and ablations |
| [`docs/reproducibility.md`](docs/reproducibility.md) | How to regenerate every number in this README |
| [`docs/roadmap.md`](docs/roadmap.md) | Project plan, milestones, Phase 2 goals |

## Code Availability

This repository is the code artifact referenced in the manuscript's Code Availability statement, as required by *Scientific Reports*' policy on custom computational tools. Recommended statement for the manuscript:

> The custom code, trained model weights, and evaluation pipeline supporting the findings of this study are openly available at [github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis](https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis), archived on Zenodo at DOI: *pending — archive a tagged release via the GitHub–Zenodo integration to mint one*.

To satisfy this: create a GitHub Release for the current tag, connect the repository to Zenodo (Zenodo → GitHub → toggle the repo on, then publish a release), and add the resulting DOI badge here and to the manuscript's Code Availability section.

## Reproducibility

- Global seed `42` fixed across NumPy, TensorFlow, and scikit-learn.
- The 80/10/10 split is stratified, seeded, and deterministic — the same images always land in the same partition.
- Metrics are computed only on the held-out test set; cross-validation uses un-augmented features so augmented copies never straddle folds.
- Generated artifacts (`outputs/`, `data/`) are git-ignored by design — regenerate everything with the CLI, nothing paper-facing is hand-typed.

```bash
trinet download && trinet prepare && trinet features
trinet train && trinet fusion && trinet evaluate --champion
trinet cross-val && trinet diversity && trinet gradcam
```

Reference environment: Apple M-series, 16 GB, Python 3.11, TensorFlow 2.16.2. Note: `tensorflow-metal` hangs on EfficientNetV2-S and errors on ConvNeXt — extract those on CPU with `trinet features --cpu`. Full notes: [`docs/reproducibility.md`](docs/reproducibility.md).

## Repository Structure

```
.
├── src/trinet/            installable package
│   ├── config.py          central configuration (paths, 14 classes, hyperparameters)
│   ├── cli.py             Typer command-line interface
│   ├── datasets/          dataset download + leakage-free preparation
│   ├── models/            backbones, fusion strategies, PSO ensemble
│   ├── training/          feature caching, head training, fine-tuning, symptom model
│   ├── evaluation/        metrics, figures, cross-validation, diversity, efficiency
│   ├── explainability/    Grad-CAM
│   ├── inference/         single-image prediction + model export
│   └── utils/             doctor / info diagnostics
├── experiments/           one-off studies (e.g. binary screening with Wilson CIs)
├── configs/               YAML experiment presets
├── docs/                  architecture, datasets, benchmark, reproducibility, model_zoo, roadmap
├── examples/              runnable usage examples (predict, batch, ONNX export, custom dataset)
├── scripts/               shell helpers (download, train, evaluate, benchmark)
├── tests/                 unit tests (metrics, models, fusion, dataset, checkpoint integrity)
├── docker/                Dockerfile + docker-compose
├── app/                   deployment stub (API / web / docker) — planned
├── archive/               original Tri-Net scripts, preserved unmodified
├── assets/                logo + figures used in docs and README
└── .github/               CI workflows + issue/PR templates
```

## Limitations

- Public composite datasets limit demographic/acquisition diversity; the leakage-free test set is modest (303 images), so metrics carry non-trivial confidence intervals.
- **No external clinical validation** — results are experimental, not clinically certified.
- Image and symptom modules are trained on **disjoint patient populations**, so genuine multimodal (joint) fusion is future work pending a paired dataset.
- The dermoscopy sub-problem is inherently hard; ~85–90% is near the field-wide ceiling even with far larger datasets and metadata.

> **Research artifact, not a medical device.** Do not use for clinical decision-making without regulatory approval and prospective validation. See [`SECURITY.md`](SECURITY.md).

## Roadmap

- Complete the backbone table (EfficientNetV2-S) and an efficiency/latency profile.
- A **hierarchical classifier** (pox-group vs dermoscopy-group → within-group heads), motivated by the strong group-separation result — the most promising route to lift fine-grained accuracy.
- Larger, higher-resolution dermoscopy data + patient metadata; self-supervised (DINOv2) features.
- A genuine multimodal model, contingent on a paired image+symptom dataset. See [`docs/roadmap.md`](docs/roadmap.md).

## Contributing

Contributions are welcome — see **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for dev setup, coding guidelines, and PR expectations. The short version: reusable code lives in `src/trinet/`, experiment-specific code lives in `experiments/`, and every reported number must be regenerable from committed code on the held-out test set.

## Citation

The original study is currently **under revision at *Scientific Reports* (Springer Nature)**; a DOI will be added here once assigned. Until then, please cite the manuscript and this reproducibility framework as follows:

```bibtex
@article{selvaraj2026trinet,
  title   = {Tri-Net: Unified Deep Learning for Skin Lesion and Symptom-Based Monkeypox Detection},
  author  = {Selvaraj, Sudharsan and Selvam, Prabu and Veeramani, Nirmala and
             Kumar B, Kiran and Ivkovi{\'c}, Nikola and Cengiz, Korhan},
  journal = {Scientific Reports},
  publisher = {Springer Nature},
  year    = {2026},
  note    = {Under revision. DOI to be added upon acceptance.}
}

@software{trinet_v2_2026,
  author  = {Selvaraj, Sudharsan},
  title   = {Tri-Net v2: A Reproducible Deep-Learning Framework for Mpox Skin-Lesion Diagnosis},
  year    = {2026},
  url     = {https://github.com/Sudharsanselvaraj/Synergistic-Deep-Learning-for-Monkeypox-Diagnosis}
}
```

See **[`CITATION.cff`](CITATION.cff)** for the machine-readable, definitive entry.

## Acknowledgments

Built on the MSLD v2 and ISIC skin-lesion datasets and the Kaggle Monkeypox symptom dataset — full sourcing and licensing in [`docs/datasets.md`](docs/datasets.md).

## License

[MIT](LICENSE)
