Upload README.md

README.md

@@ -0,0 +1,260 @@
+# MS3SEG: Pre-trained Models for MS Lesion Segmentation
+
+[![Paper](https://img.shields.io/badge/Paper-Scientific%20Data-blue.svg)](https://doi.org/10.6084/m9.figshare.30393475)
+[![Dataset](https://img.shields.io/badge/Dataset-Figshare-blue.svg)](https://doi.org/10.6084/m9.figshare.30393475)
+[![Code](https://img.shields.io/badge/Code-GitHub-black.svg)](https://github.com/Mahdi-Bashiri/MS3SEG)
+[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
+
+Pre-trained deep learning models for Multiple Sclerosis lesion segmentation from the **MS3SEG dataset**.
+
+> **Note:** These are representative models from Fold 4 of our 5-fold cross-validation. Complete training code and all fold results are available in our [GitHub repository](https://github.com/Mahdi-Bashiri/MS3SEG).
+
+---
+
+## 📋 Repository Contents
+
+```
+MS3SEG/
+├── kfold_brain_segmentation_20250924_232752_unified_focal_loss/models/
+│   ├── binary_abnormal_wmh/      # Binary MS lesion segmentation
+│   │   ├── u-net_fold_4_best.h5        
+│   │   ├── unet++_fold_4_best.h5       
+│   │   ├── unetr_fold_4_best.h5       
+│   │   └── swinunetr_fold_4_best.h5    
+│   │
+│   ├── binary_ventricles/        # Binary ventricle segmentation
+│   │   ├── u-net_fold_4_best.h5        
+│   │   ├── unet++_fold_4_best.h5       
+│   │   ├── unetr_fold_4_best.h5       
+│   │   └── swinunetr_fold_4_best.h5     
+│   │
+│   └── multi_class/              # 4-class tri-mask segmentation
+│   │   ├── u-net_fold_4_best.h5        
+│   │   ├── unet++_fold_4_best.h5       
+│   │   ├── unetr_fold_4_best.h5       
+│   │   └── swinunetr_fold_4_best.h5  
+│
+├── figures/
+│   ├── training_curves/          # Loss and metrics across epochs
+│   └── sample_predictions/       # Visual results from paper
+│
+├── config/
+│   └── experiment_config.json    # Model training configuration
+└── README.md                     # This file
+```
+
+**Total Size:** ~1.2 GB (12 model files)
+
+---
+
+## 🎯 Model Overview
+
+### Segmentation Scenarios
+
+| Scenario | Classes | Description |
+|----------|---------|-------------|
+| **Multi-class** | 4 | Background, Ventricles, Normal WMH, Abnormal WMH (MS lesions) |
+| **Binary Lesion** | 2 | MS lesions vs. everything else |
+| **Binary Ventricle** | 2 | Ventricles vs. everything else |
+
+### Model Architectures
+
+- **U-Net**: Classic encoder-decoder with skip connections
+- **U-Net++**: Nested skip pathways for improved feature propagation
+- **UNETR**: Vision Transformer encoder with CNN decoder
+- **Swin UNETR**: Hierarchical shifted-window attention
+
+All models trained on **256×256 axial FLAIR images** from 64 patients (Fold 4 training set).
+
+---
+
+## 📊 Performance (Fold 4 Validation Results)
+
+### Multi-Class Segmentation (Dice Score)
+
+| Model | Ventricles | Normal WMH | Abnormal WMH | Mean |
+|-------|:----------:|:----------:|:------------:|:----:|
+| **U-Net** | **0.8967** | **0.5935** | **0.6709** | **0.7204** |
+| U-Net++ | 0.8904 | 0.5881 | 0.6512 | 0.7099 |
+| UNETR | 0.8401 | 0.4692 | 0.6632 | 0.6575 |
+| Swin UNETR | 0.8608 | 0.5203 | 0.5920 | 0.6577 |
+
+### Binary Lesion Segmentation
+
+| Model | Dice | IoU | HD95 (mm) |
+|-------|:----:|:---:|:---------:|
+| **U-Net** | **0.7407** | 0.5882 | 32.64 |
+| U-Net++ | 0.5930 | 0.4215 | 35.12 |
+| UNETR | 0.6632 | 0.4963 | 40.85 |
+| Swin UNETR | 0.5841 | 0.4127 | 38.19 |
+
+### Binary Ventricle Segmentation
+
+| Model | Dice | IoU | HD95 (mm) |
+|-------|:----:|:---:|:---------:|
+| **U-Net** | **0.8967** | 0.8130 | 9.52 |
+| U-Net++ | 0.8904 | 0.8026 | 10.18 |
+| Swin UNETR | 0.8608 | 0.7560 | 12.73 |
+| UNETR | 0.8401 | 0.7240 | 14.92 |
+
+*Results are from validation set of Fold 4. See [paper](https://doi.org/10.6084/m9.figshare.30393475) for complete 5-fold statistics.*
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install tensorflow>=2.10.0 nibabel numpy
+```
+
+### Load and Use Models
+
+```python
+from tensorflow import keras
+from huggingface_hub import hf_hub_download
+import numpy as np
+
+# Download model
+model_path = hf_hub_download(
+    repo_id="Bawil/MS3SEG",
+    filename="models/multi_class/U-Net_fold4.h5"
+)
+
+# Load model
+model = keras.models.load_model(model_path, compile=False)
+
+# Prepare your data (256x256 FLAIR image)
+# image shape: (batch, 256, 256, 1)
+predictions = model.predict(image)
+
+# For multi-class: get class labels
+pred_classes = np.argmax(predictions, axis=-1)
+# Classes: 0=background, 1=ventricles, 2=normal WMH, 3=abnormal WMH
+
+# For binary: apply threshold
+pred_binary = (predictions > 0.5).astype(np.uint8)
+```
+
+### Download All Models for One Scenario
+
+```python
+from huggingface_hub import snapshot_download
+
+# Download entire scenario folder
+snapshot_download(
+    repo_id="Bawil/MS3SEG",
+    allow_patterns="models/multi_class/*",
+    local_dir="./ms3seg_models"
+)
+```
+
+---
+
+## 📝 Input Requirements
+
+- **Format**: NIfTI (.nii.gz) or NumPy array
+- **Modality**: T2-FLAIR (axial plane)
+- **Dimensions**: 256 × 256 pixels
+- **Channels**: 1 (grayscale)
+- **Preprocessing**: 
+  - Co-registered to FLAIR space
+  - Brain-extracted
+  - Intensity normalized to [0, 1]
+  - Voxel spacing: ~0.9 × 0.9 × 5.7 mm³
+
+See [preprocessing scripts](https://github.com/Mahdi-Bashiri/MS3SEG/tree/main/preprocessing) in our GitHub repository.
+
+---
+
+## 📖 Dataset Information
+
+**MS3SEG** is a Multiple Sclerosis MRI dataset with unique **tri-mask annotations**:
+
+- **100 patients** from Iranian cohort (1.5T Toshiba scanner)
+- **~2000 annotated slices** with expert consensus
+- **4 annotation classes**: Background, Ventricles, Normal WMH, Abnormal WMH
+- **Multiple sequences**: T1w, T2w, T2-FLAIR (axial + sagittal)
+
+**Dataset Access:** [Figshare Repository](https://doi.org/10.6084/m9.figshare.30393475) (CC-BY-4.0 License)
+
+---
+
+## 🔧 Model Training Details
+
+All models were trained with:
+
+- **Loss Function**: Unified Focal Loss (combining Dice and Focal components)
+- **Optimizer**: Adam (lr=1e-4)
+- **Batch Size**: 4
+- **Epochs**: 100 (with early stopping, patience=10)
+- **Data Split**: 64 train / 16 validation patients (Fold 4)
+- **Framework**: TensorFlow 2.10+
+
+Complete training configuration available in `config.json`.
+
+---
+
+## 📚 Citation
+
+If you use these models in your research, please cite our paper:
+
+```bibtex
+@article{bashiri2026ms3seg,
+  title={A Multiple Sclerosis MRI Dataset with Tri-Mask Annotations for Lesion Segmentation},
+  author={Bashiri Bawil, Mahdi and Shamsi, Mousa and Ghalehasadi, Aydin and Jafargholkhanloo, Ali Fahmi and Shakeri Bavil, Abolhassan},
+  journal={Scientific Data},
+  year={2026},
+  doi={10.6084/m9.figshare.30393475},
+  publisher={Nature Publishing Group}
+}
+```
+
+---
+
+## 🔗 Resources
+
+- **📄 Paper**: [Scientific Data](https://doi.org/10.6084/m9.figshare.30393475)
+- **💾 Dataset**: [Figshare](https://doi.org/10.6084/m9.figshare.30393475)
+- **💻 Code**: [GitHub](https://github.com/Mahdi-Bashiri/MS3SEG)
+- **📧 Contact**: mehdi.bashiri.b@gmail.com
+
+---
+
+## ⚠️ Important Notes
+
+1. **Fold 4 Only**: These models represent one fold (Fold 4) from our 5-fold cross-validation. They demonstrate representative performance but should not be considered the final "best" models across all folds.
+
+2. **Research Use**: These models are provided for research purposes. Clinical validation is required before any diagnostic application.
+
+3. **Data Compatibility**: Models expect preprocessed data matching our pipeline. See [preprocessing documentation](https://github.com/Mahdi-Bashiri/MS3SEG/tree/main/preprocessing).
+
+4. **Complete Results**: For all 5 folds and comprehensive evaluation, see our [GitHub repository](https://github.com/Mahdi-Bashiri/MS3SEG) and [paper](https://doi.org/10.6084/m9.figshare.30393475).
+
+5. **Storage Considerations**: Full 5-fold model collection (38GB) is available upon request. These representative Fold 4 models (6GB) are sufficient for most use cases.
+
+---
+
+## 📜 License
+
+**Models**: CC-BY-4.0 (same as dataset)  
+**Code**: MIT License (see [GitHub](https://github.com/Mahdi-Bashiri/MS3SEG))
+
+You are free to use, modify, and distribute these models with appropriate attribution.
+
+---
+
+## 🙏 Acknowledgments
+
+Data acquired at Golgasht Medical Imaging Center, Tabriz, Iran. Ethics approval: Tabriz University of Medical Sciences (IR.TBZMED.REC.1402.902).
+
+---
+
+<div align="center">
+
+**Made by the MS3SEG Team**
+
+[GitHub](https://github.com/Mahdi-Bashiri/MS3SEG) • [Paper](https://doi.org/10.6084/m9.figshare.30393475) • [Dataset](https://doi.org/10.6084/m9.figshare.30393475)
+
+</div>