MIT-BIH stands for Massachusetts Institute of Technology – Beth Israel Hospital (now Beth Israel Deaconess Medical Center, Boston).
An interactive, high-fidelity cardiac signal processing experimentation ground and AI-assisted classification playground. This project supports reading standard ambulatory electrocardiogram (ECG) data from the MIT-BIH Arrhythmia Database, running peak detection algorithms, training classifiers via PyTorch and PEFT (LoRA), and querying a clinical knowledge base via a local RAG chatbot with strict hallucination guardrails.
| Feature | Stack | Description |
|---|---|---|
| 🫀 Signal Explorer | wfdb · scipy · plotly |
Browse PhysioNet records, visualize R-peaks, upload custom CSVs |
| 🎛️ Pan-Tompkins Sandbox | scipy.signal.filtfilt |
Tune bandpass cutoffs & integration windows in real-time |
| 🤖 Heartbeat Classifier | scikit-learn · PyTorch |
Toggle between Random Forest and 1D ResNet + LoRA |
| 🔬 Grad-CAM XAI | PyTorch · PEFT |
Visualize which waveform regions drive the model's prediction |
| 🔍 Anomaly Autoencoder | PyTorch |
Unsupervised anomaly detection via reconstruction MSE |
| 💬 LLM Clinical Explainer | Ollama · gemma4 |
One-click cardiologist-grade morphology reports |
| 📚 OKF + RAG Chat | TF-IDF · Ollama · Gemini |
Clinical Q&A with strict hallucination guardrails |
| ⚡ Spark Pipeline | PySpark |
Distributed signal transformations with DAG visualization |
| 📺 Bedside Monitor Sim | Streamlit · plotly |
Real-time scrolling waveform with on-the-fly classification |
The MIT-BIH Arrhythmia Database is a landmark resource in biomedical engineering and cardiology — the first generally available standard test material for evaluating arrhythmia detectors.
| Detail | Description |
|---|---|
| Origin | Collaborative research between the Massachusetts Institute of Technology (MIT) and the Beth Israel Hospital (BIH) in Boston, beginning in 1975. The project was guided by Prof. Roger Mark. |
| Data Collection | ECG recordings were obtained by the BIH Arrhythmia Laboratory between 1975 and 1979 from over 4,000 long-term Holter recordings (≈60% inpatients, ≈40% outpatients). |
| Content | 48 half-hour excerpts of two-channel ambulatory ECG recordings from 47 subjects. 23 recordings represent routine clinical encounters; 25 were selected for clinically significant arrhythmias. |
| Annotation | Each record was independently annotated by two or more cardiologists, with discrepancies resolved to produce ≈110,000 computer-readable beat annotations. |
| Distribution | First distributed on 9-track digital tape in 1980, then on CD-ROM in 1989, and finally made freely available online via PhysioNet (MIT Laboratory for Computational Physiology) between 1999 and 2005. |
| Clinical Impact | Standardized how arrhythmia analyzers are tested, encouraging manufacturers to compete on objectively measurable performance. Remains the most widely cited benchmark for ECG signal processing, AI, and medical device development. |
mit-bih/
├── Dockerfile # Container configuration
├── docker-compose.yml # Multi-service orchestration (App + Spark)
├── pyproject.toml # uv-managed dependencies & scripts
├── LICENSE # MIT License (© 2026 bernardbdas)
├── README.md # This file
├── GUIDE.md # Clinical & technical user guide
├── justfile # Task runner targets
├── knowledge_base/ # Open Knowledge Format (OKF) Bundle
│ ├── index.md # Knowledge catalog index
│ ├── dataset_manifest.md # PhysioNet database manifest
│ └── ... # 18 concept, reference, runbook, and guide articles
├── demo_samples/ # Pre-extracted clinical CSV samples
│ └── README.md # Ground truth metadata
├── models/
│ ├── trained/ # Random Forest classifiers (.joblib)
│ └── weights/ # DL weights (LoRA adapters, ResNet, Autoencoder)
└── src/
├── mit_bih/ # Core application package
│ ├── __init__.py # CLI entrypoint
│ ├── signal/ # Signal processing (Butterworth, Pan-Tompkins)
│ ├── ml/ # Machine learning classifiers
│ ├── dl/ # Deep learning (PyTorch, PEFT, Grad-CAM, Autoencoder)
│ ├── assistant/ # RAG assistant & OKF parsing
│ ├── pipeline/ # PySpark pipelines & PhysioNet downloader
│ └── web/ # Streamlit UI application
└── tests/ # Integration & verification tests
Prerequisites:
uv(fast Python package manager) and Python ≥ 3.12
# 1. Install uv (macOS / Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Clone & install dependencies
git clone https://github.com/bernardbdas/mit-bih.git
cd mit-bih
uv sync
# 3. Launch the web application
uv run mit-bih
# → Open http://localhost:8501 in your browserOr use the just task runner:
just start # Launch the Streamlit app
just test # Run integration tests
just format # Format codebase with ruff| Platform | Backend | Setup |
|---|---|---|
| macOS (Apple Silicon) | Metal Performance Shaders (MPS) | Auto-detected — no configuration needed |
| Linux (NVIDIA GPU) | CUDA | Install proprietary drivers → verify with nvidia-smi |
| CPU Fallback | PyTorch CPU | Works everywhere, slower for training |
- The Process: Raw ECG → Cascaded Bandpass (5–15 Hz) → Differentiate → Square → Moving Window Integration (150 ms)
- The Sandbox: Adjust passband frequencies and integration window dynamically with Streamlit sliders
| Model | Type | Description |
|---|---|---|
| Random Forest | Classic ML | Pre-trained on 180-sample segments centered at R-peaks |
| 1D CNN + PEFT LoRA | Deep Learning | Fine-tuned via LoRA adapters targeting proj_linear |
| Hugging Face ResNet | Deep Learning | Transfer learning from pretrained image classification |
- Grad-CAM Focus Heatmap: Visualize which waveform regions the neural network relies on for classification
- LLM Clinical Explainer: One-click cardiologist-grade reports via local Ollama (
gemma4) analyzing predictions, RR-intervals, and autoencoder MSE
- Convolutional autoencoder trained exclusively on normal sinus beats
- Flags out-of-distribution morphology via reconstruction MSE thresholding
- Original vs. reconstructed waveform overlay for visual comparison
Hallucination Prevention: TF-IDF similarity threshold of
0.05+ greedy decoding (temperature = 0)
| Backend | Description |
|---|---|
| Ollama (Recommended) | Local gemma4 / qwen2.5:3b with zero-temperature inference |
| PyTorch SLM | In-process Qwen/Qwen2.5-0.5B-Instruct on MPS/CUDA |
| Gemini API | Online cloud inference with API key |
-
Pipeline: Large-scale parallel transformations (Rescale → Diff → Square → Integrate)
-
DAG Visualization: Spark Web UI at
http://localhost:4040 -
Java Dependency: Requires Java 17 LTS (or 11 LTS)
# macOS brew install openjdk@17 # Ubuntu/Debian sudo apt install openjdk-17-jdk # Arch / CachyOS sudo pacman -S jdk17-openjdk
| Path | Contents |
|---|---|
models/trained/ |
Random Forest classifiers (.joblib) |
models/weights/peft_adapter/ |
LoRA adapter config & weights |
models/weights/hf_resnet_finetuned.pt |
Hugging Face ResNet weights |
models/weights/autoencoder.pt |
Anomaly autoencoder checkpoint |
Dynamic reset buttons embedded throughout the interface (Sidebar, Playback Panel, Filter Sandbox, Hyperparameters) — instantly restore configurations to clinical defaults.
| Document | Description |
|---|---|
| GUIDE.md | Step-by-step clinical & technical walkthrough |
| demo_samples/README.md | Categorized clinical CSV samples with ground truth |
| JUST.md | Justfile task runner reference |
Orchestrate the full stack (Streamlit app + Spark master + Spark worker):
docker compose up -d
# App → http://localhost:8501
# Spark UI → http://localhost:8080# Build
podman build -t mit-bih -f Dockerfile .
# Run (CPU)
podman run -d -p 8501:8501 --name mit-bih-app mit-bih
# Run (NVIDIA GPU passthrough)
podman run -d -p 8501:8501 \
--device nvidia.com/gpu=all \
--security-opt label=disable \
--name mit-bih-app mit-bihThis project is licensed under the MIT License — see LICENSE for details.
© 2026 bernardbdas