Skip to content

GUIDE.md

Latest commit

 

History

History
130 lines (104 loc) · 7.68 KB

GUIDE.md

File metadata and controls

130 lines (104 loc) · 7.68 KB
Raw

📖 ECG AI Playground: Clinical & Technical User Guide

This guide provides a comprehensive walkthrough of the MIT-BIH Cardiac Playground & OKF-RAG System web application. MIT-BIH stands for Massachusetts Institute of Technology – Beth Israel Hospital (now Beth Israel Deaconess Medical Center, Boston). The MIT-BIH Arrhythmia Database (1975–1979) contains 48 half-hour two-channel ambulatory ECG recordings from 47 subjects, annotated by multiple cardiologists, and remains the gold-standard benchmark for arrhythmia detection research.

This application is designed for clinical researchers, data scientists, and engineers to explore signal processing, deep learning fine-tuning, unsupervised anomaly detection, explainable AI (XAI), and clinical retrieval.

🚀 Accessing the Application

🌐 Launching via Chrome Dev

If you are running the project locally or inside a container, you can launch the app and access it using Google Chrome Dev (or your preferred web browser):

  1. Start the App: Ensure the Streamlit server is running by executing: 
    just start
    or 
    uv run mit-bih
  2. Open Chrome Dev: Open your terminal and run Chrome Dev with security flags if you plan to do advanced remote diagnostics, or simply launch it normally: 
    google-chrome-unstable http://localhost:8501
    or open Google Chrome Dev from your desktop environment and navigate to: 
    http://localhost:8501

🎨 Walkthrough of UI Tabs

graph TD
    A[Streamlit Web App] --> B[Tab 1: Signal Explorer & Classifier]
    A --> C[Tab 2: Pan-Tompkins Sandbox]
    A --> D[Tab 3: PyTorch & PEFT LoRA]
    A --> E[Tab 4: OKF Knowledge Base]
    A --> F[Tab 5: RAG Chat Assistant]
    A --> G[Tab 6: Apache Spark Pipeline]
Loading

📈 Tab 1: Signal Explorer & Classifier

The Explorer tab serves as the primary interface for visualizing ECG signals, running QRS peak detectors, and obtaining model classification predictions.

Key Features:

  1. Dynamic Dataset Headers & Clinical Details:
    • Whenever you select a dataset (e.g., mitdb, afdb, nstdb) from the sidebar, the tab header updates automatically to display the full medical name of the database.
    • A descriptive clinical alert box displays details regarding the records, origin, and characteristics of the selected database.
  2. ECG Waveform & Detected R-Peaks:
    • Renders a multi-second interactive Plotly signal chart overlaid with detected R-peaks (triangle markers) and clinical annotations (circular markers).
  3. Heartbeat Classification Breakdown Table:
    • Lists every detected heartbeat index, its location in seconds, the predicted AAMI class (N, S, V, F, Q), classification confidence, and unsupervised anomaly metrics.
    • Cells containing abnormal clinical classes (like Ventricular V or Supraventricular S) are highlighted in red and orange respectively.
  4. Grad-CAM Explainable AI (XAI) Focus Heatmap:
    • When a heartbeat is selected, checking the 🔍 Show Grad-CAM Focus Heatmap box displays a Plotly signal trace colored by the model's neural attention weight (gradient-weighted class activation mapping). Red regions indicate segments that the model heavily relied on for its classification decision.
  5. Unsupervised Anomaly Overlay:
    • Checking the anomaly highlight box calculates the reconstruction Mean Squared Error (MSE) from a convolutional autoencoder trained strictly on normal beats.
    • Flags anomalies (⚠️ Yes) in the beats table when MSE exceeds the sidebar slider threshold.
    • Plots the original waveform (solid line) and the autoencoder's reconstructed trace (dashed line) together to visually display morphological divergence.
  6. LLM-Based AI Clinical Explainer:
    • Features a button "💬 Explain Heartbeat with gemma4". When clicked, it packages AAMI predictions, model confidence, pre/post-RR intervals, and autoencoder MSE scores into a structured cardiology prompt.
    • Queries the local Ollama server running gemma4 to return an expert clinical diagnosis, diagnostic rationale, and recommendations.

Suggested Screenshot File: screenshots/explorer_tab.png

🎛️ Tab 2: Pan-Tompkins Signal Processing Sandbox

This tab provides a step-by-step visual sandbox to debug the Pan-Tompkins algorithm:

  1. Interactive Tuning Sliders:
    • Bandpass Low Cutoff (Hz) (Default: 5.0): Filters low-frequency baseline drift and respiratory artifacts.
    • Bandpass High Cutoff (Hz) (Default: 15.0): Filters high-frequency muscle noise and powerline interference.
    • Integration Window Width (ms) (Default: 150): Adjusts the width of the moving window integration.
  2. Intermediate Waveforms:
    • Plots the signal at each stage: Raw Signal $\rightarrow$ Bandpass Filtered $\rightarrow$ Derivative Filtered $\rightarrow$ Squared Signal $\rightarrow$ Moving Window Integration.
  3. Reset Button:
    • Clicking "🔄 Reset Filters" instantly restores all bandpass cutoffs and window widths to standard clinical defaults.

Suggested Screenshot File: screenshots/pan_tompkins_sandbox.png

🧬 Tab 3: Deep Learning Model Fine-Tuning & Training

Tab 3 provides a control panel to train models directly from the UI:

  1. Target Selector:
    • Choose between fine-tuning the PyTorch 1D ResNet with PEFT LoRA, fine-tuning the Hugging Face ResNet, or training the Unsupervised Anomaly Autoencoder.
  2. Hyperparameter Sliders:
    • Configure Training Epochs, Learning Rate, and Batch Size.
  3. Training Console:
    • Displays real-time training progress logs and loss curves.
  4. Reset Button:
    • Click "🔄 Reset Hyperparameters" to restore standard clinical training rates and epochs.

Suggested Screenshot File: screenshots/peft_training_tab.png

📚 Tab 4 & 5: OKF Knowledge Base & RAG Chat Assistant

These tabs allow clinical inquiries against the Open Knowledge Format (OKF) Bundle:

  1. Knowledge Catalog Index:
    • Browses through 20 reference guides, concepts, and runbooks covering arrhythmia classification, noise testing, and sleep polysomnography.
  2. RAG Chat Panel:
    • Enter questions regarding QRS detection or cardiac pathology.
    • TF-IDF Hallucination Guardrails: Irrelevant queries (e.g., asking about history, pop culture, or unrelated fields) trigger a strict guardrail intercept (⚠️ Guardrail Alert: Query Blocked) since their similarity index falls below 0.05.

Suggested Screenshot File: screenshots/rag_chat_tab.png

⚡ Step-by-Step Simulation: Dynamic Bedside Monitor

To run a live simulation of a bedside patient monitor scrolling waveform with real-time on-the-fly classifications:

  1. Go to the Signal Explorer (Tab 1) and scroll down to Live Signal Playback Sandbox.
  2. Adjust Playback Speed (steps/sec) and Visible Samples Window.
  3. Click ▶️ Play Animation.
  4. Observe the waveform drawing itself from left to right.
  5. Watch R-peaks get detected on-the-fly, with clinical letters (🟢 N, 🔴 V, 🟠 S, 🟣 F, ⚪ Q) flashing directly above peaks as they scroll across the screen!
  6. Click ⏸️ Pause Animation at any time, or click "🔄 Reset Playback" to restore default simulation rates.

📂 Models & Weights Registry Reference

For portability and reusability, trained models are saved in the project root:

  • models/trained/ $\rightarrow$ Random Forest classifiers.
  • models/weights/peft_adapter/ $\rightarrow$ PyTorch LoRA adapter configuration and weights.
  • models/weights/hf_resnet_finetuned.pt $\rightarrow$ Hugging Face ResNet weights.
  • models/weights/autoencoder.pt $\rightarrow$ Unsupervised Autoencoder weights.