shareefch1413 commited on
Commit
389313c
·
verified ·
1 Parent(s): cc5a225

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +120 -99
README.md CHANGED
@@ -1,125 +1,146 @@
1
- # 07_Python_Source_Code: ACL-LKNet Modular Python Package
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2
 
3
- This directory provides the clean, production-grade Python source code (standalone `.py` modules and command-line interfaces) for **ACL-LKNet**. It operates completely independently of Jupyter notebooks and can be deployed directly in local workstation, HPC cluster, or cloud environments.
4
 
5
- ---
 
 
 
6
 
7
- ## Directory Architecture
8
 
9
- ```
10
- 07_Python_Source_Code/
11
- ├── requirements.txt # Minimal, verified package dependencies
12
- ├── train_cv.py # Command-line training and cross-validation interface
13
- ├── evaluate_ensemble.py # Command-line evaluation, bootstrap CI, and DeLong testing
14
- ├── generate_gradcam.py # Command-line high-resolution Grad-CAM++ visualizer
15
- └── src/ # Modular package library
16
- ├── __init__.py # Package exports
17
- ├── config.py # Master Config dataclass (Single Source of Truth)
18
- ├── dataset.py # Tri-planar MRI volume loader and anatomical augmentations
19
- ├── utils.py # EMA weight averaging, checkpoint recovery, RNG seeds
20
- ├── train.py # Phase 1 (SSL) & Phase 2 (Supervised 5-Fold CV) engine
21
- ├── evaluate.py # Evaluation suite (1,000-sample bootstrap CIs, DeLong test)
22
- └── models/
23
- ├── __init__.py # Model registry
24
- ├── backbone.py # ConvNeXt-Tiny, ResNet-18, and RepLKNet backbone stems
25
- ├── slice_attention.py # Parametric slice sequence attention pooling
26
- ├── cross_view_fusion.py# 2-Head Tri-Planar self-attention view fusion
27
- ├── msm.py # Masked Slice Modeling self-supervised autoencoder
28
- └── acl_lknet.py # Full end-to-end tri-planar architecture assembly
29
- ```
30
 
31
  ---
32
 
33
- ## Installation & Setup
 
 
34
 
35
- 1. **Create and Activate Virtual Environment**:
36
- ```bash
37
- python -m venv acl_env
38
- # On Linux / macOS:
39
- source acl_env/bin/activate
40
- # On Windows:
41
- acl_env\Scripts\activate
42
- ```
 
43
 
44
- 2. **Install Dependencies**:
45
- ```bash
46
- pip install -r requirements.txt
47
- ```
48
 
49
  ---
50
 
51
- ## Command-Line Usage (CLI)
52
 
53
- ### 1. Training & 5-Fold Cross-Validation (`train_cv.py`)
 
 
54
 
55
- * **Train a Single Fold (e.g., Fold 1)**:
56
- ```bash
57
- python train_cv.py --data_dir /path/to/mrnet --fold 1 --output_dir ./checkpoints
58
- ```
 
59
 
60
- * **Run Full Stratified 5-Fold Cross-Validation**:
61
- ```bash
62
- python train_cv.py --data_dir /path/to/mrnet --cv --output_dir ./checkpoints
63
- ```
64
 
65
- * **Phase 1: Masked Slice Modeling (MSM) Pretraining**:
66
- ```bash
67
- python train_cv.py --data_dir /path/to/mrnet --ssl_pretrain --output_dir ./ssl_checkpoints
68
- ```
69
 
70
- * **Ablation Re-run (Standard ResNet-18 Backbone - RQ1)**:
71
- ```bash
72
- python train_cv.py --data_dir /path/to/mrnet --fold 1 --backbone resnet18 --output_dir ./checkpoints_resnet
73
- ```
74
 
75
- ---
 
 
 
 
 
 
 
 
 
 
76
 
77
- ### 2. Diagnostic Evaluation & Bootstrap CIs (`evaluate_ensemble.py`)
78
-
79
- * **Evaluate 5-Fold Soft-Voting Ensemble on Official Test Cohort**:
80
- ```bash
81
- python evaluate_ensemble.py \
82
- --data_dir /path/to/mrnet \
83
- --checkpoints_dir ./checkpoints \
84
- --split test \
85
- --n_bootstraps 1000 \
86
- --output_json test_results.json
87
- ```
88
-
89
- * **Evaluate an Individual Checkpoint**:
90
- ```bash
91
- python evaluate_ensemble.py \
92
- --data_dir /path/to/mrnet \
93
- --checkpoint ./checkpoints/acl_lknet_fold1_best.pt \
94
- --split valid
95
- ```
96
 
97
  ---
98
 
99
- ### 3. Grad-CAM++ Anatomical Saliency Visualizations (`generate_gradcam.py`)
100
-
101
- * **Generate High-Resolution Saliency Map for a Given Exam**:
102
- ```bash
103
- python generate_gradcam.py \
104
- --data_dir /path/to/mrnet \
105
- --checkpoint ./checkpoints/acl_lknet_fold1_best.pt \
106
- --exam_id 1130 \
107
- --output_image gradcam_exam_1130.png
108
- ```
109
-
110
- * **Automatically Select the Most Saliency-Informative Positive Tear**:
111
- ```bash
112
- python generate_gradcam.py \
113
- --data_dir /path/to/mrnet \
114
- --checkpoint ./checkpoints/acl_lknet_fold1_best.pt \
115
- --auto_positive \
116
- --output_image gradcam_positive_tear.png
117
- ```
118
 
119
  ---
120
 
121
- ## Architectural & Anatomical Guardrails
122
 
123
- * **Unit Batch Size with Gradient Accumulation**: To prevent GPU out-of-memory (OOM) errors on 15--16 GB VRAM devices while maintaining volumetric tensor integrity, the training loop runs with `batch_size = 1` and `accumulation_steps = 8` (effective batch size $B_{\text{eff}} = 8$).
124
- * **Anatomical Symmetry Invariant**: Random horizontal and vertical flipping are strictly disabled in `dataset.py` to preserve knee joint chirality, collateral ligament distinctions, and oblique ACL insertion vectors.
125
- * **Positive Class Imbalance Weighting**: All loss functions apply positive weighting $w_{\text{pos}} = 3.3$ to compensate for the 23.3% positive tear prevalence in clinical populations.
 
 
 
 
 
 
1
+ ---
2
+ language:
3
+ - en
4
+ license: mit
5
+ library_name: timm
6
+ pipeline_tag: image-classification
7
+ tags:
8
+ - medical-imaging
9
+ - knee-mri
10
+ - acl-tear-detection
11
+ - deep-learning
12
+ - convnext
13
+ - self-attention
14
+ - masked-slice-modeling
15
+ - radiology
16
+ - orthopedics
17
+ datasets:
18
+ - stanford-mrnet
19
+ metrics:
20
+ - roc_auc
21
+ - accuracy
22
+ - f1
23
+ model-index:
24
+ - name: ACL-LKNet
25
+ results:
26
+ - task:
27
+ type: image-classification
28
+ name: Knee MRI ACL Tear Detection
29
+ dataset:
30
+ type: stanford-mrnet
31
+ name: Stanford MRNet Locked Test Cohort (N=120)
32
+ metrics:
33
+ - type: roc_auc
34
+ value: 0.9639
35
+ name: AUROC
36
+ - type: precision_recall_auc
37
+ value: 0.9293
38
+ name: AUPRC
39
+ - type: accuracy
40
+ value: 0.8167
41
+ name: Accuracy
42
+ - type: specificity
43
+ value: 0.9394
44
+ name: Specificity
45
+ - type: sensitivity
46
+ value: 0.6667
47
+ name: Sensitivity
48
+ - type: f1
49
+ value: 0.7660
50
+ name: F1 Score
51
+ ---
52
 
53
+ # ACL-LKNet: Self-Supervised Large-Kernel Network for ACL Tear Detection in Knee MRI
54
 
55
+ [![Paper](https://img.shields.io/badge/Paper-IEEE%20TMI%20%2F%20MedIA-blue)](https://github.com)
56
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
57
+ [![Model Type](https://img.shields.io/badge/Architecture-ConvNeXt--Tiny%20%2B%20MHA-purple)](https://github.com)
58
+ [![AUROC](https://img.shields.io/badge/Official%20MRNet%20AUROC-0.9639-brightgreen)](https://github.com)
59
 
60
+ **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.
61
 
62
+ Developed as part of a doctoral investigation in computational musculoskeletal radiology, ACL-LKNet combines:
63
+ 1. **Large-Kernel 2D Backbone (ConvNeXt-Tiny)**: Large $7 \times 7$ depthwise convolutions capturing the complete oblique trajectory of intra-articular ligaments.
64
+ 2. **Masked Slice Modeling (MSM)**: Volumetric self-supervised pretext reconstruction across anisotropic slice stacks.
65
+ 3. **Parametric Slice Attention**: Dynamic slice sequence pooling that outputs explicit, interpretable slice attention weights $\alpha_{p,s}$.
66
+ 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}}$).
67
+ 5. **Strict Anatomical Invariants**: No horizontal/vertical flipping during training to preserve internal knee joint chirality and oblique ACL orientation.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
68
 
69
  ---
70
 
71
+ ## Benchmark Performance on Stanford MRNet
72
+
73
+ 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):
74
 
75
+ | Diagnostic Metric | ACL-LKNet (5-Fold Ensemble) | 95% Bootstrap CI | Stanford MRNet Baseline (Bien et al., 2018) | Absolute $\Delta$ Gain |
76
+ | :--- | :---: | :---: | :---: | :---: |
77
+ | **AUROC** | **0.9639** | **[0.9277, 0.9919]** | 0.9370 | **+0.0269** |
78
+ | **AUPRC** | **0.9293** | **[0.8492, 0.9889]** | -- | -- |
79
+ | **Accuracy** | **81.67%** | **[75.00%, 88.33%]** | 82.50% | $-0.0083$ |
80
+ | **Specificity** | **93.94%** | **[87.69%, 98.59%]** | 96.80% | $-0.0286$ |
81
+ | **Sensitivity** | **66.67%** | **[53.22%, 79.25%]** | 75.90% | $-0.0923$ |
82
+ | **F1-Score** | **0.7660** | **[0.6585, 0.8519]** | -- | -- |
83
+ | **Brier Score** | **0.1184** | **[0.0891, 0.1520]** | -- | Well-Calibrated |
84
 
85
+ > **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.
 
 
 
86
 
87
  ---
88
 
89
+ ## Quickstart: Python Inference via Hugging Face Hub
90
 
91
+ ```python
92
+ import torch
93
+ from huggingface_hub import hf_hub_download
94
 
95
+ # 1. Download model weights from Hugging Face Hub
96
+ checkpoint_path = hf_hub_download(
97
+ repo_id="shareefch1413/ACL-LKNet",
98
+ filename="finetune_best.pt"
99
+ )
100
 
101
+ # 2. Instantiate model architecture
102
+ from src.config import Config
103
+ from src.models.acl_lknet import create_model_from_config
 
104
 
105
+ config = Config(backbone_name="convnext_tiny")
106
+ model = create_model_from_config(config)
 
 
107
 
108
+ state_dict = torch.load(checkpoint_path, map_location="cpu")
109
+ model.load_state_dict(state_dict["ema_state_dict"] if "ema_state_dict" in state_dict else state_dict["model_state_dict"])
110
+ model.eval()
 
111
 
112
+ # 3. Predict on tri-planar MRI volume (Sagittal, Coronal, Axial)
113
+ # Each volume tensor is shape: (1, 24, 3, 224, 224)
114
+ dummy_exam = {
115
+ "sagittal": torch.randn(1, 24, 3, 224, 224),
116
+ "coronal": torch.randn(1, 24, 3, 224, 224),
117
+ "axial": torch.randn(1, 24, 3, 224, 224)
118
+ }
119
+
120
+ with torch.no_grad():
121
+ output = model(dummy_exam)
122
+ tear_probability = torch.sigmoid(output["logits"]).item()
123
 
124
+ print(f"Predicted ACL Tear Probability: {tear_probability * 100:.2f}%")
125
+ ```
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
126
 
127
  ---
128
 
129
+ ## Clinical Interpretability: Grad-CAM++ and Slice Attention
130
+
131
+ * **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.
132
+ * **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.
133
+ * **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]$).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
134
 
135
  ---
136
 
137
+ ## Citation
138
 
139
+ ```bibtex
140
+ @article{acl_lknet2026,
141
+ title={ACL-LKNet: Anatomically Constrained Large-Kernel Network with Multi-Plane Self-Attention for Volumetric ACL Tear Detection in Knee MRI},
142
+ author={PhD Candidate in Biomedical Engineering and Computational Medicine},
143
+ journal={IEEE Transactions on Medical Imaging (Preprint / PhD Dissertation Protocol)},
144
+ year={2026}
145
+ }
146
+ ```