Upload README.md with huggingface_hub

README.md

@@ -1,167 +1,175 @@
-# ECG-Mamba Cardiac Abnormality Classification
-
-A deep learning project implementing the Mamba architecture for ECG cardiac abnormality classification using the PTB-XL dataset from PhysioNet.
-
-## Overview
-
-This project demonstrates the application of the Mamba state space model for multi-lead ECG signal classification. The model is trained to classify cardiac abnormalities into diagnostic superclasses including NORM, MI, STTC, CD, and HYP.
-
-## Features
-
-- **Mamba Architecture**: Utilizes the efficient Mamba state space model for sequence modeling
-- **PTB-XL Dataset**: Automated downloading and preprocessing of ECG data from PhysioNet
-- **Multi-lead ECG**: Processes all 12 standard ECG leads
-- **GPU Accelerated**: Optimized for GPU training with CUDA support
-- **Visualization**: Includes prediction visualization for model interpretation
+---
+license: mit
+tags:
+- ecg
+- mamba
+- cardiac
+- classification
+- medical
+- ptb-xl
+- state-space-model
+datasets:
+- PTB-XL
+language:
+- en
+library_name: pytorch
+pipeline_tag: image-classification
+---
+
+# ECG-Mamba: Cardiac Abnormality Classification
+
+## Model Description
+
+ECG-Mamba is a deep learning model that leverages the Mamba state space architecture for classifying cardiac abnormalities from 12-lead ECG signals. The model is trained on the PTB-XL dataset from PhysioNet.
 
 ## Model Architecture
 
-The ECGMambaClassifier consists of:
-- Linear embedding layer (12 channels → 64 dimensions)
-- 2 Mamba layers with state space modeling
-- Layer normalization
-- Classification head for multi-class prediction
-
-Key hyperparameters:
-- `d_model`: 64 (model dimension)
-- `d_state`: 16 (state space dimension)
-- `d_conv`: 4 (convolution kernel size)
-- `expand`: 2 (expansion factor)
-
-## Requirements
-
-- Python 3.7+
-- PyTorch
-- mamba-ssm
-- causal-conv1d >= 1.2.0
-- wfdb
-- pandas
-- numpy
-- scikit-learn
-- matplotlib
-- requests
-
-## Installation
-
-```bash
-pip install torch mamba-ssm causal-conv1d wfdb pandas numpy scikit-learn matplotlib requests
-```
+- **Base Architecture**: Mamba (Selective State Space Model)
+- **Input**: 12-lead ECG signals (1000 timesteps × 12 channels at 100Hz)
+- **Output**: 5-class classification (NORM, MI, STTC, CD, HYP)
+- **Parameters**:
+  - Model dimension (d_model): 64
+  - State space dimension (d_state): 16
+  - Number of Mamba layers: 2
+  - Convolution kernel size (d_conv): 4
+  - Expansion factor: 2
 
-**Note**: This project requires a GPU to run the Mamba implementation efficiently. For Google Colab, ensure Runtime type is set to T4 GPU or better.
+## Intended Use
 
-## Usage
+This model is designed for:
+- Research purposes in cardiac abnormality detection
+- Educational demonstrations of Mamba architecture on medical signals
+- Baseline comparison for ECG classification tasks
 
-### Running in Google Colab
+**Note**: This model is NOT intended for clinical diagnosis or medical decision-making.
 
-1. Open the notebook in Google Colab
-2. Set Runtime type to GPU (Runtime → Change runtime type → T4 GPU)
-3. Run all cells sequentially
+## Training Data
 
-The notebook will automatically:
-1. Install all dependencies
-2. Download a subset of PTB-XL dataset (500 records)
-3. Preprocess and normalize ECG signals
-4. Train the Mamba model for 10 epochs
-5. Evaluate on test set and visualize predictions
+- **Dataset**: PTB-XL (PhysioNet)
+- **Training samples**: ~400 records (80% of 500 record subset)
+- **Validation samples**: ~100 records (20% of 500 record subset)
+- **Sampling rate**: 100 Hz (low resolution)
+- **Signal length**: 10 seconds (1000 samples)
+- **Preprocessing**: Standardization (zero mean, unit variance per channel)
 
-### Dataset
+## Performance
 
-The notebook uses the PTB-XL dataset, a large publicly available electrocardiography dataset containing:
-- 21,837 clinical 12-lead ECGs from 18,885 patients
-- 10 second recordings at 100Hz (low resolution) or 500Hz (high resolution)
-- Multiple diagnostic statements by cardiologists
+On the test subset (500 records):
+- **Training Accuracy**: ~75%
+- **Test Accuracy**: ~70%
 
-For this implementation, we use:
-- 500 records (configurable via `NUM_RECORDS`)
-- Low resolution (100Hz) for faster processing
-- Single diagnostic superclass per record for simplified classification
+**Important**: These metrics are from a small-scale demonstration. For production use, train on the full PTB-XL dataset (21,837 records).
 
-Dataset citation:
-```
-Wagner, P., Strodthoff, N., Bousseljot, R., Samek, W., & Schaeffter, T. (2020).
-PTB-XL, a large publicly available electrocardiography dataset (version 1.0.3).
-PhysioNet. https://doi.org/10.13026/x4td-x982
-```
-
-## Training Results
-
-Typical training performance (10 epochs, 500 records):
-- Training Accuracy: ~75%
-- Test Accuracy: ~70%
-- Training time: ~2-3 minutes on T4 GPU
+## Diagnostic Classes
 
-## Model Performance
+| Class | Description |
+|-------|-------------|
+| NORM | Normal ECG |
+| MI | Myocardial Infarction |
+| STTC | ST/T Change |
+| CD | Conduction Disturbance |
+| HYP | Hypertrophy |
 
-The model achieves competitive performance on cardiac abnormality classification:
-- Fast inference time thanks to Mamba's efficient architecture
-- Good generalization on multi-class ECG classification
-- Potential for improvement with larger datasets and longer training
+## Usage
 
-## Visualization
+```python
+import torch
+import numpy as np
+from mamba_ssm import Mamba
 
-The notebook includes visualization of:
-- Multiple ECG leads with offset for clarity
-- True vs. predicted diagnostic classes
-- Sample predictions from the test set
+# Load model (you'll need to save/load weights separately)
+model = ECGMambaClassifier(n_classes=5)
+model.load_state_dict(torch.load('model_weights.pth'))
+model.eval()
 
-## Project Structure
+# Prepare your ECG data
+# ecg_signal: numpy array of shape (1000, 12)
+ecg_tensor = torch.tensor(ecg_signal, dtype=torch.float32).unsqueeze(0)
 
-```
-.
-├── ECG_Mamba_Colab_Test.ipynb  # Main Jupyter notebook
-├── README.md                     # This file
-├── LICENSE                       # MIT License
-└── ptb_xl_data/                 # Downloaded dataset (created at runtime)
+# Inference
+with torch.no_grad():
+    logits = model(ecg_tensor)
+    predicted_class = torch.argmax(logits, dim=1)
 ```
 
-## Diagnostic Classes
+## Limitations
 
-The model classifies ECG signals into the following diagnostic superclasses:
-- **NORM**: Normal ECG
-- **MI**: Myocardial Infarction
-- **STTC**: ST/T Change
-- **CD**: Conduction Disturbance
-- **HYP**: Hypertrophy
+1. **Small training set**: Model trained on only 500 records for demonstration
+2. **Simplified classification**: Single-label classification (many ECGs have multiple conditions)
+3. **Class imbalance**: Not addressed in this implementation
+4. **No clinical validation**: Not validated on independent clinical datasets
+5. **Research use only**: Not approved for medical diagnosis
 
-## Future Improvements
+## Ethical Considerations
 
-- [ ] Increase dataset size for better generalization
-- [ ] Implement cross-validation for robust performance metrics
-- [ ] Add data augmentation techniques
-- [ ] Experiment with deeper Mamba architectures
-- [ ] Support for multi-label classification
-- [ ] Model deployment pipeline
-- [ ] Real-time ECG inference API
+- This model should NOT be used for clinical diagnosis
+- Medical decisions should only be made by qualified healthcare professionals
+- The model may exhibit biases present in the PTB-XL dataset
+- Performance may vary across different patient populations
 
-## References
+## Training Procedure
 
-1. **Mamba**: Gu, A., & Dao, T. (2023). Mamba: Linear-Time Sequence Modeling with Selective State Spaces.
-2. **PTB-XL**: Wagner et al. (2020). PTB-XL, a large publicly available electrocardiography dataset.
-3. **PhysioNet**: Goldberger et al. (2000). PhysioBank, PhysioToolkit, and PhysioNet.
+### Preprocessing
+1. Download PTB-XL records from PhysioNet
+2. Extract low-resolution (100Hz) 12-lead ECG signals
+3. Filter for single-label diagnostic superclass
+4. Standardize signals (zero mean, unit variance)
 
-## License
+### Training Hyperparameters
+- **Optimizer**: AdamW
+- **Learning rate**: 1e-3
+- **Batch size**: 32
+- **Epochs**: 10
+- **Loss function**: CrossEntropyLoss
+- **Hardware**: NVIDIA T4 GPU
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### Data Augmentation
+None applied in this implementation.
 
-## Acknowledgments
+## Environmental Impact
 
-- PhysioNet for providing the PTB-XL dataset
-- The Mamba-SSM team for the efficient state space model implementation
-- Google Colab for providing free GPU resources
+- **Hardware**: NVIDIA T4 GPU (Google Colab)
+- **Training time**: ~2-3 minutes
+- **Carbon footprint**: Minimal due to short training time
 
 ## Citation
 
-If you use this code in your research, please cite:
-
+### This Model
 ```bibtex
 @software{ecg_mamba_2024,
   title={ECG-Mamba: Cardiac Abnormality Classification using Mamba Architecture},
-  author={Your Name},
   year={2024},
-  url={https://github.com/yourusername/ecg-mamba}
+  url={https://huggingface.co/your-username/ecg-mamba}
+}
+```
+
+### PTB-XL Dataset
+```bibtex
+@article{wagner2020ptbxl,
+  title={PTB-XL, a large publicly available electrocardiography dataset},
+  author={Wagner, Patrick and Strodthoff, Nils and Bousseljot, Ralf-Dieter and Kreiseler, Dieter and Lunze, Fatima I and Samek, Wojciech and Schaeffter, Tobias},
+  journal={Scientific Data},
+  volume={7},
+  number={1},
+  pages={154},
+  year={2020}
 }
 ```
 
-## Contact
+### Mamba
+```bibtex
+@article{gu2023mamba,
+  title={Mamba: Linear-Time Sequence Modeling with Selective State Spaces},
+  author={Gu, Albert and Dao, Tri},
+  journal={arXiv preprint arXiv:2312.00752},
+  year={2023}
+}
+```
+
+## Model Card Authors
+
+This model card was created as part of the ECG-Mamba project.
+
+## Model Card Contact
 
-For questions or collaboration opportunities, please open an issue on GitHub.
+For questions or issues, please open an issue on the [GitHub repository](https://github.com/skkuhg/ecg-mamba).