README.md

metadata

title: ECG-FM API
emoji: 🫀
colorFrom: blue
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

curl https://mystic-cbk-ecg-fm-api.hf.space/health

Full ECG Analysis

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

{
  "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

# 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
• Paper: ECG-FM: A Foundation Model for ECG Analysis
• 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