Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,146 @@
+---
+language:
+- en
+license: mit
+library_name: timm
+pipeline_tag: image-classification
+tags:
+- medical-imaging
+- knee-mri
+- acl-tear-detection
+- deep-learning
+- convnext
+- self-attention
+- masked-slice-modeling
+- radiology
+- orthopedics
+datasets:
+- stanford-mrnet
+metrics:
+- roc_auc
+- accuracy
+- f1
+model-index:
+- name: ACL-LKNet
+  results:
+  - task:
+      type: image-classification
+      name: Knee MRI ACL Tear Detection
+    dataset:
+      type: stanford-mrnet
+      name: Stanford MRNet Locked Test Cohort (N=120)
+    metrics:
+    - type: roc_auc
+      value: 0.9639
+      name: AUROC
+    - type: precision_recall_auc
+      value: 0.9293
+      name: AUPRC
+    - type: accuracy
+      value: 0.8167
+      name: Accuracy
+    - type: specificity
+      value: 0.9394
+      name: Specificity
+    - type: sensitivity
+      value: 0.6667
+      name: Sensitivity
+    - type: f1
+      value: 0.7660
+      name: F1 Score
+---
+
+# ACL-LKNet: Self-Supervised Large-Kernel Network for ACL Tear Detection in Knee MRI
+
+[![Paper](https://img.shields.io/badge/Paper-IEEE%20TMI%20%2F%20MedIA-blue)](https://github.com)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Model Type](https://img.shields.io/badge/Architecture-ConvNeXt--Tiny%20%2B%20MHA-purple)](https://github.com)
+[![AUROC](https://img.shields.io/badge/Official%20MRNet%20AUROC-0.9639-brightgreen)](https://github.com)
+
+**ACL-LKNet** is an anatomically grounded deep learning architecture specifically engineered for automated Anterior Cruciate Ligament (ACL) tear detection from tri-planar (Sagittal, Coronal, and Axial) volumetric knee MRI examinations.
+
+Developed as part of a doctoral investigation in computational musculoskeletal radiology, ACL-LKNet combines:
+1. **Large-Kernel 2D Backbone (ConvNeXt-Tiny)**: Large $7 \times 7$ depthwise convolutions capturing the complete oblique trajectory of intra-articular ligaments.
+2. **Masked Slice Modeling (MSM)**: Volumetric self-supervised pretext reconstruction across anisotropic slice stacks.
+3. **Parametric Slice Attention**: Dynamic slice sequence pooling that outputs explicit, interpretable slice attention weights $\alpha_{p,s}$.
+4. **Tri-Planar Cross-Attention Fusion**: 2-head self-attention operating over learned plane positional embeddings ($e_{\text{sag}}, e_{\text{cor}}, e_{\text{axi}}$).
+5. **Strict Anatomical Invariants**: No horizontal/vertical flipping during training to preserve internal knee joint chirality and oblique ACL orientation.
+
+---
+
+## Benchmark Performance on Stanford MRNet
+
+Evaluated on the locked, official **Stanford MRNet benchmark test set** ($N=120$ examinations, 54 tears, 66 controls) with empirical 95% bootstrap confidence intervals ($N=1{,}000$ iterations):
+
+| Diagnostic Metric | ACL-LKNet (5-Fold Ensemble) | 95% Bootstrap CI | Stanford MRNet Baseline (Bien et al., 2018) | Absolute $\Delta$ Gain |
+| :--- | :---: | :---: | :---: | :---: |
+| **AUROC** | **0.9639** | **[0.9277, 0.9919]** | 0.9370 | **+0.0269** |
+| **AUPRC** | **0.9293** | **[0.8492, 0.9889]** | -- | -- |
+| **Accuracy** | **81.67%** | **[75.00%, 88.33%]** | 82.50% | $-0.0083$ |
+| **Specificity** | **93.94%** | **[87.69%, 98.59%]** | 96.80% | $-0.0286$ |
+| **Sensitivity** | **66.67%** | **[53.22%, 79.25%]** | 75.90% | $-0.0923$ |
+| **F1-Score** | **0.7660** | **[0.6585, 0.8519]** | -- | -- |
+| **Brier Score** | **0.1184** | **[0.0891, 0.1520]** | -- | Well-Calibrated |
+
+> **Statistical Significance (RQ1)**: Paired DeLong test comparing ConvNeXt-Tiny against ResNet-18 yields **$z = 3.864, p = 0.000104$** ($p < 0.001$), establishing the statistical superiority of large receptive fields for elongated ligament structures.
+
+---
+
+## Quickstart: Python Inference via Hugging Face Hub
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+
+# 1. Download model weights from Hugging Face Hub
+checkpoint_path = hf_hub_download(
+    repo_id="your-username/ACL-LKNet",
+    filename="acl_lknet_fold1_best.pt"
+)
+
+# 2. Instantiate model architecture
+from src.config import Config
+from src.models.acl_lknet import create_model_from_config
+
+config = Config(backbone_name="convnext_tiny")
+model = create_model_from_config(config)
+
+state_dict = torch.load(checkpoint_path, map_location="cpu")
+model.load_state_dict(state_dict["ema_state_dict"] if "ema_state_dict" in state_dict else state_dict["model_state_dict"])
+model.eval()
+
+# 3. Predict on tri-planar MRI volume (Sagittal, Coronal, Axial)
+# Each volume tensor is shape: (1, 24, 3, 224, 224)
+dummy_exam = {
+    "sagittal": torch.randn(1, 24, 3, 224, 224),
+    "coronal":  torch.randn(1, 24, 3, 224, 224),
+    "axial":    torch.randn(1, 24, 3, 224, 224)
+}
+
+with torch.no_grad():
+    output = model(dummy_exam)
+    tear_probability = torch.sigmoid(output["logits"]).item()
+
+print(f"Predicted ACL Tear Probability: {tear_probability * 100:.2f}%")
+```
+
+---
+
+## Clinical Interpretability: Grad-CAM++ and Slice Attention
+
+* **Parametric Slice Attention Profiles**: Learns autonomous focus on central intercondylar notch slices (11--15/24) where the ACL is anatomically situated without requiring slice-level bounding box supervision.
+* **High-Resolution Grad-CAM++**: Hooks into ConvNeXt-Tiny Stage 2 ($14 \times 14$ feature map) to generate intra-articular gradient heatmaps localized to the femoral footprint and midsubstance tear site.
+* **Decision Curve Analysis (DCA)**: Demonstrates superior clinical net benefit over "treat all" and "treat none" policies across all relevant surgical intervention thresholds ($p_t \in [0.10, 0.75]$).
+
+---
+
+## Citation
+
+```bibtex
+@article{acl_lknet2026,
+  title={ACL-LKNet: Anatomically Constrained Large-Kernel Network with Multi-Plane Self-Attention for Volumetric ACL Tear Detection in Knee MRI},
+  author={PhD Candidate in Biomedical Engineering and Computational Medicine},
+  journal={IEEE Transactions on Medical Imaging (Preprint / PhD Dissertation Protocol)},
+  year={2026}
+}
+```