Create README.md

README.md

@@ -1,3 +1,72 @@
----
-license: mit
----
+---
+language: en
+license: mit
+library_name: pytorch
+tags:
+- medical-imaging
+- mri
+- 3d-resnet
+- monai
+- oncology
+- breast-cancer
+- sustainable-ai
+- explainable-ai
+metrics:
+- roc_auc
+pipeline_tag: image-classification
+---
+
+# Advanced Multi-Stream 3D-ResNet for ODELIA (Phase 3)
+
+This repository contains the "Better Model" (Phase 3) for breast cancer classification on multi-parametric MRI. This version represents the most stable and optimized iteration, featuring a hybrid architecture designed to handle high-resolution 3D sequences with extreme memory efficiency.
+
+## 🛠 Key Engineering Breakthroughs (Phase 3)
+- **Instance Normalization Integration:** Replaced Batch Normalization with **InstanceNorm 3D**. This critical fix allows the model to maintain stable gradients even with a Batch Size of 1, preventing the collapse observed in earlier versions.
+- **Dynamic Temporal Fusion:** Uses a Multi-Stream approach where the Kinetic stream processes a variable number of post-contrast phases.
+- **Improved Temporal Aggregation:** Transitioned to **Temporal Mean Pooling** for feature fusion, providing a more robust "global temporal summary" compared to complex recurrent layers (LSTM/RNN) on this specific dataset volume.
+- **Explainable AI (XAI):** Full support for **3D Grad-CAM** visualization on the T2 structural stream.
+
+## Model Description
+- **Developed by:** [Your Name/Pseudo]
+- **Architecture:** Multi-Stream 3D ResNet-18 (Custom InstanceNorm version).
+- **Task:** 3 Multi-class classification (Normal, Benign, Malignant).
+- **Input Modalities:** 1. **T2 Stream:** Structural 3D MRI volume.
+  2. **Kinetics Stream:** Temporal sequence of subtraction volumes (Post_i - Pre).
+- **Spatial Resolution:** 128 x 128 x 64.
+
+## Technical Details
+
+### Architecture Components
+- **Encoders:** Two parallel 3D ResNet-18 backbones with `InstanceNorm3D`.
+- **Temporal Handling:** The kinetics encoder processes each time point independently; features are then aggregated via mean pooling across the time dimension.
+- **Classification Head:** A 2-layer MLP with **40% Dropout** to prevent overfitting on complex features.
+
+### Training Protocol
+- **Optimizer:** AdamW (LR = 2e-4, Weight Decay = 1e-4).
+- **Scheduler:** CosineAnnealingLR (T_max=50) for smooth convergence.
+- **Loss:** **Focal Loss (gamma=2.0)** with dynamic class weighting to prioritize the rare "Benign" and "Malignant" cases.
+- **Optimization:** Mixed Precision (AMP) and Gradient Accumulation (steps=4).
+
+## Performance & Sustainability
+The model was trained on the **IDUN HPC Cluster**. 
+- **Carbon Tracking:** Training included environmental footprint monitoring (~0.25 kW/GPU on a low-carbon Norwegian grid).
+- **Stability:** Evaluation shows consistent convergence across 5 folds, validated by a rigorous audit of the patient split.
+
+## How to Load the Model
+This model requires the `MultiStreamResNet` class from the `utils.py` file.
+
+```python
+import torch
+from utils import MultiStreamResNet
+
+# Initialize model with Phase 3 dimensions
+model = MultiStreamResNet(num_classes=3, hidden_dim=256)
+
+# Load weights for a specific fold
+model.load_state_dict(torch.load("best_resnet_odelia_fold0.pth", map_location="cpu"))
+model.eval()
+```
+
+## Explainability (Grad-CAM)
+The model includes a wrapper for Explainable AI. It targets the layer4 of the T2 encoder to generate 3D heatmaps, 
+helping to identify the specific anatomical regions influencing the "Malignant" prediction.