unknownBrain/BioHCL-SSSM-Pediatric-Pneumonia

BioHCL-SSSM: Hierarchical Convolutional State-Space Hybrid Architecture for Pediatric Pneumonia Diagnosis

Official repository containing the pre-trained weights, modular source code, comparative benchmarks, and cross-validation evaluations for the BioHCL-SSSM model on the Guangzhou Pediatric Chest X-Ray Cohort (Kermany et al., Cell 2018; 5,856 images).

---

📌 Repository Overview

This central repository provides:

1. Model Checkpoints (checkpoints/):
   • best_student_cv.pt: Peak student model (Fold 2: 99.81% Val Acc, 0.9987 Val F1, 14.01M params, 8.56 GFLOPs).
   • cross_validation/model_fold_1.pt to 10.pt: Full 10-fold cross-validation ensemble models.
   • ablations/: Model weights for key architectural variants (best_student_bioprior.pt, best_student_single_cnn.pt, best_student_no_positional.pt, baseline_resnet50.pt).
2. Modular Code (src/):
   • PyTorch implementation of BioHCLSSSM, LinearBioSSSMBlock, DualChainExtractor, HierarchicalConvBlock, and QuadraticPositionalEncoder.
   • Standardized datasets, pre-processing, loss formulations (BioPINNLoss), and evaluation pipelines.
3. Structured Results (results/):
   • Comprehensive CSV deliverables for SOTA benchmarks, component ablations, layer hyperparameter deduction, and 10-fold cross-validation.
4. Publication Figures (figures/):
   • 10-fold ROC/PR curves with standard deviation envelopes, confusion matrices, and explainability heatmaps (Attention, GradCAM, LIME, SHAP).

---

🏗️ Architecture Design

                     ┌────────────────────────────────────────────────────────┐
                     │              Input Chest X-Ray (3 x 224 x 224)         │
                     └───────────────────────────┬────────────────────────────┘
                                                 │
                     ┌───────────────────────────┴────────────────────────────┐
                     │                 DUAL-CHAIN FEATURE EXTRACTOR           │
                     ├───────────────────────────┬────────────────────────────┤
                     ▼                           ▼                            │
         [Hierarchical Conv Block]    [DenseNet-121 Semantic Backbone]       │
         Multi-kernel (3x3, 5x5, 7x7) Dense connectivity (1024 -> 256)        │
                     │                           │                            │
                     └─────────────┬─────────────┘                            │
                                   ▼                                          │
                     ┌───────────────────────────┐                            │
                     │  Cross-Gated Fusion +     │                            │
                     │  Quadratic Positional Enc │                            │
                     └─────────────┬─────────────┘                            │
                                   ▼                                          │
                     ┌───────────────────────────┐                            │
                     │  Selective State Space    │ ◄── Linear O(N) Recurrence │
                     │  (SSSM) Sequence Engine   │ ◄── Continuous-to-Discrete │
                     │  (3 Blocks, d_state=64)   │ ◄── Zero-Order Hold (ZOH)  │
                     └─────────────┬─────────────┘                            │
                                   ▼                                          │
                     ┌───────────────────────────┐                            │
                     │  Additive Identity Skip   │                            │
                     │  Connection Highway       │                            │
                     └─────────────┬─────────────┘                            │
                                   ▼                                          │
                     ┌───────────────────────────┐                            │
                     │ Global Pooling & Head     │ ──► [NORMAL vs PNEUMONIA]  │
                     └───────────────────────────┘

---

📊 Evaluation & Benchmarks

1. Approved 10-Fold Cross-Validation Metrics (results/5_10_fold_cross_validation_metrics.csv)

Evaluated across the entire cohort (5,232 images pooled):

• Mean Accuracy: 99.37% ± 0.33%
• Mean Precision: 0.9969 ± 0.0036
• Mean Recall (Sensitivity): 0.9946 ± 0.0059
• Mean Specificity: 0.9911 ± 0.0103
• Mean F1-Score: 0.9957 ± 0.0022
• Mean ROC-AUC: 0.9929 ± 0.0039
• Pooled Confusion Matrix: 3,862 TP, 1,337 TN, 12 FP, 21 FN (99.37% global accuracy, only 33 errors).
• Peak Fold: Fold 2 achieved 99.81% accuracy, 0.9987 F1, 100% recall, 99.26% specificity (checkpoints/best_student_cv.pt).

2. State-of-the-Art Comparative Benchmarks (results/1_sota_benchmarks_master.csv)

Tested on the official 624-image Kermany held-out test split (234 Normal, 390 Pneumonia):

Model	Architecture Family	Params (M)	FLOPs (G)	Accuracy (%)	Precision (%)	Recall (%)	Specificity (%)	F1-Score (%)	ROC-AUC (%)	Source
ResNet-50	Classic CNN	25.56	4.12	92.63	90.00	99.23	81.62	94.39	98.31	Diagnostics 2026
DenseNet-121	Classic CNN	7.98	2.88	92.62	91.18	99.23	81.60	95.04	98.78	Appl. Sci. 2020
Xception	Classic CNN	22.91	8.38	95.03	94.26	98.00	89.96	96.08	98.10	AJSE 2022
ViT-Base (ViT-B/16)	Vision Transformer	86.57	17.56	92.47	89.80	99.00	81.20	94.18	97.10	arXiv:2312.07965
DeiT-Small	Vision Transformer	22.05	4.60	93.75	92.40	97.95	86.75	95.10	97.80	ICML 2021
Swin-T	Hierarchical ViT	27.52	2.98	95.99	95.74	97.95	92.74	96.83	99.18	Diagnostics 2026
BioHCL-SSSM (Proposed Best)	State-Space Hybrid	14.01	8.56	96.47	96.25	98.21	93.59	97.22	99.37	Ours (Empirical Test Set)

---

💻 Quickstart & Inference

import torch
from PIL import Image
from huggingface_hub import hf_hub_download
from src.models.biohcl_sssm import BioHCLSSSM
from src.dataset import get_transforms

# 1. Download and load the pre-trained model
ckpt_path = hf_hub_download(
    repo_id="unknownBrain/BioHCL-SSSM-Pediatric-Pneumonia",
    filename="checkpoints/best_student_cv.pt"
)
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model = BioHCLSSSM(num_classes=2, embed_dim=512, chain_mode="dual", num_sssm_blocks=3)
state_dict = torch.load(ckpt_path, map_location=device)
if "model_state_dict" in state_dict:
    state_dict = state_dict["model_state_dict"]
model.load_state_dict(state_dict)
model.to(device).eval()

# 2. Predict on a chest X-ray image
_, eval_transform = get_transforms(img_size=224)
image = Image.open("path_to_xray.jpeg").convert("RGB")
tensor = eval_transform(image=np.array(image))["image"].unsqueeze(0).to(device)

with torch.no_grad():
    logits, _ = model(tensor)
    probs = torch.softmax(logits, dim=1)[0]
    classes = ["NORMAL", "PNEUMONIA"]
    pred = classes[torch.argmax(probs).item()]
    print(f"Prediction: {pred} (Confidence: {probs.max().item():.4f})")

---

📜 Citation & License

This project is licensed under the MIT License. Dataset credit: Guangzhou Women and Children’s Medical Center (Kermany et al., Cell 2018).