Spaces:
Sleeping
Sleeping
| title: ECG-FM API | |
| emoji: 🫀 | |
| colorFrom: blue | |
| # FORCE REBUILD: Import logic fix for fairseq_signals deployed at 2025-08-25 08:50 UTC - AGGRESSIVE CACHE INVALIDATION - Build trigger attempt #3 - HF Spaces cache issue detected | |
| colorTo: purple | |
| sdk: docker | |
| sdk_version: "latest" | |
| app_file: server.py | |
| pinned: false | |
| # 🏥 ECG-FM Dual Model Production API | |
| ## 🚀 **Production-Ready ECG Analysis with Clinical Interpretation** | |
| A comprehensive ECG analysis API using **ECG-FM (ECG Foundation Model)** with dual-model architecture for clinical diagnosis and physiological parameter extraction. | |
| ## 🌟 **Key Features** | |
| ### **✅ Clinical ECG Interpretation** | |
| - **17 Clinical Labels** from MIMIC-IV-ECG dataset | |
| - **Rhythm Classification** (Normal, AF, Bradycardia, etc.) | |
| - **Abnormality Detection** (MI, BBB, AV blocks, etc.) | |
| - **Clinical Confidence Scores** | |
| ### **✅ Physiological Parameter Extraction** | |
| - **Heart Rate (BPM)**: 30-200 range | |
| - **QRS Duration (ms)**: 40-200 range | |
| - **QT Interval (ms)**: 300-600 range | |
| - **PR Interval (ms)**: 100-300 range | |
| - **QRS Axis (degrees)**: -180 to +180 range | |
| ### **✅ Rich ECG Features** | |
| - **1024+ Dimensional Embeddings** | |
| - **Temporal Patterns** (rhythm characteristics) | |
| - **Morphological Features** (waveform analysis) | |
| - **Spatial Relationships** (12-lead correlations) | |
| ## 🏗️ **Architecture** | |
| ### **Dual Model Strategy** | |
| 1. **`mimic_iv_ecg_finetuned.pt`** (1.08 GB) | |
| - Clinical classifier with 17 labels | |
| - Priority loading for immediate clinical availability | |
| 2. **`mimic_iv_ecg_physionet_pretrained.pt`** (1.09 GB) | |
| - Feature extractor for physiological parameters | |
| - Secondary loading for comprehensive analysis | |
| ### **API Endpoints** | |
| - **`/health`** - Health check and model status | |
| - **`/analyze`** - Full ECG analysis (both models) | |
| - **`/extract_features`** - Feature extraction (pretrained model) | |
| - **`/assess_quality`** - Signal quality assessment | |
| ## 🚀 **Quick Start** | |
| ### **API Base URL** | |
| ``` | |
| https://mystic-cbk-ecg-fm-api.hf.space | |
| ``` | |
| ### **Health Check** | |
| ```bash | |
| curl https://mystic-cbk-ecg-fm-api.hf.space/health | |
| ``` | |
| ### **Full ECG Analysis** | |
| ```python | |
| import requests | |
| import json | |
| # Load your ECG data | |
| ecg_signal = [[...], [...], ...] # 12 leads | |
| payload = { | |
| "signal": ecg_signal, | |
| "fs": 500, | |
| "lead_names": ["I", "II", "III", "aVR", "aVL", "aVF", "V1", "V2", "V3", "V4", "V5", "V6"], | |
| "recording_duration": len(ecg_signal[0]) / 500.0 | |
| } | |
| response = requests.post( | |
| "https://mystic-cbk-ecg-fm-api.hf.space/analyze", | |
| json=payload | |
| ) | |
| if response.status_code == 200: | |
| result = response.json() | |
| print(f"Rhythm: {result['clinical_analysis']['rhythm']}") | |
| print(f"Heart Rate: {result['clinical_analysis']['heart_rate']} BPM") | |
| print(f"QRS Duration: {result['clinical_analysis']['qrs_duration']} ms") | |
| print(f"QT Interval: {result['clinical_analysis']['qt_interval']} ms") | |
| print(f"Signal Quality: {result['signal_quality']}") | |
| print(f"Features: {len(result['features'])} dimensions") | |
| ``` | |
| ## 📊 **Response Format** | |
| ### **Clinical Analysis** | |
| ```json | |
| { | |
| "clinical_analysis": { | |
| "rhythm": "Normal Sinus Rhythm", | |
| "heart_rate": 72.5, | |
| "qrs_duration": 85.2, | |
| "qt_interval": 420.1, | |
| "pr_interval": 165.3, | |
| "axis_deviation": "Normal", | |
| "abnormalities": [], | |
| "confidence": 0.89, | |
| "physiological_parameters": { | |
| "heart_rate": 72.5, | |
| "qrs_duration": 85.2, | |
| "qt_interval": 420.1, | |
| "pr_interval": 165.3, | |
| "qrs_axis": 15.2 | |
| } | |
| }, | |
| "features": [0.123, -0.456, ...], | |
| "signal_quality": "Excellent", | |
| "processing_time": 2.45 | |
| } | |
| ``` | |
| ## 🔬 **Clinical Labels (17)** | |
| The model detects these clinical conditions: | |
| 1. **Poor data quality** | |
| 2. **Sinus rhythm** | |
| 3. **Premature ventricular contraction** | |
| 4. **Tachycardia** | |
| 5. **Ventricular tachycardia** | |
| 6. **Supraventricular tachycardia with aberrancy** | |
| 7. **Atrial fibrillation** | |
| 8. **Atrial flutter** | |
| 9. **Bradycardia** | |
| 10. **Accessory pathway conduction** | |
| 11. **Atrioventricular block** | |
| 12. **1st degree atrioventricular block** | |
| 13. **Bifascicular block** | |
| 14. **Right bundle branch block** | |
| 15. **Left bundle branch block** | |
| 16. **Infarction** | |
| 17. **Electronic pacemaker** | |
| ## ⚡ **Performance** | |
| - **Startup Time**: 5-10 minutes (first deployment) | |
| - **Inference Time**: 2-5 seconds per ECG | |
| - **Memory Usage**: ~2.5GB total | |
| - **Concurrent Requests**: 10+ simultaneous analyses | |
| ## 🛠️ **Technical Details** | |
| ### **Dependencies** | |
| - **PyTorch 2.1.0** with CUDA 11.x compatibility | |
| - **fairseq-signals** for ECG-FM model loading | |
| - **FastAPI** for high-performance API | |
| - **NumPy 1.26.4** for compatibility | |
| ### **Model Loading Strategy** | |
| - **Direct HF Loading**: Models downloaded from `wanglab/ecg-fm` | |
| - **Cache Persistence**: Uses `/app/.cache/huggingface` | |
| - **Priority Loading**: Clinical model first, feature model second | |
| ### **Docker Configuration** | |
| - **Base Image**: Python 3.9-slim | |
| - **Port**: 7860 (HF Spaces standard) | |
| - **Cache**: Persistent HF model cache | |
| ## 📈 **Use Cases** | |
| ### **Clinical Research** | |
| - **Population Studies**: Analyze large ECG datasets | |
| - **Clinical Trials**: Automated ECG interpretation | |
| - **Medical Education**: ECG analysis training | |
| ### **Healthcare** | |
| - **Screening Programs**: Mass ECG analysis | |
| - **Telemedicine**: Remote ECG interpretation | |
| - **Emergency Medicine**: Rapid ECG assessment | |
| ### **Research & Development** | |
| - **Feature Engineering**: Extract 1024+ dimensional features | |
| - **Model Training**: Use features for custom classifiers | |
| - **Validation Studies**: Compare with expert interpretations | |
| ## 🔧 **Deployment** | |
| ### **Hugging Face Spaces** | |
| - **Automatic Deployment**: Git push triggers build | |
| - **Model Caching**: Persistent between restarts | |
| - **Scalability**: Handles multiple concurrent requests | |
| ### **Local Deployment** | |
| ```bash | |
| # Clone repository | |
| git clone https://huggingface.co/spaces/mystic-cbk/mystic-cbk-ecg-fm-api | |
| # Install dependencies | |
| pip install -r requirements_hf_spaces.txt | |
| # Run server | |
| uvicorn server:app --host 0.0.0.0 --port 7860 | |
| ``` | |
| ## 📚 **Documentation** | |
| - **API Reference**: `/docs` (Swagger UI) | |
| - **ReDoc**: `/redoc` (Alternative documentation) | |
| - **Health Check**: `/health` (System status) | |
| ## 🤝 **Contributing** | |
| This API is based on the official **ECG-FM** model from: | |
| - **Repository**: [wanglab/ECG-FM](https://github.com/bowang-lab/ECG-FM) | |
| - **Paper**: [ECG-FM: A Foundation Model for ECG Analysis](https://arxiv.org/abs/2308.08487) | |
| - **License**: MIT License | |
| ## 📄 **License** | |
| MIT License - See LICENSE file for details. | |
| ## 🆘 **Support** | |
| - **Issues**: Report via GitHub Issues | |
| - **Documentation**: Check `/docs` endpoint | |
| - **Health Status**: Monitor `/health` endpoint | |
| --- | |
| **Built with ❤️ using ECG-FM Foundation Model** | |
| **Deployed on Hugging Face Spaces for global accessibility** |