Clasificación de Bloqueos de Rama (LBBB/RBBB) mediante Machine Learning

Este proyecto implementa modelos de Machine Learning para la clasificación morfológica intraventricular en señales de electrocardiograma (ECG), enfocándose en la detección automática de bloqueos de rama izquierda y derecha (LBBB, RBBB) frente a ritmo normal (NORM).

El dataset combinado incluye anotaciones más granulares para algunos registros (bloqueos completos e incompletos: CRBBB, IRBBB, CLBBB, ILBBB, disponibles en PTB-XL), pero esa distinción no está disponible en CPSC2018 ni en Chapman-Shaoxing, que solo etiquetan LBBB/RBBB de forma unificada. Para poder combinar las tres bases sin descartar ninguna y maximizar el volumen de datos por clase, se optó por trabajar con 3 clases objetivo (NORM / LBBB / RBBB), colapsando en cada base la granularidad completo/incompleto donde existía.

📊 Bases de Datos Utilizadas y Justificación Metodológica

Para garantizar la robustez, generalización y estabilidad temporal del modelo, el entrenamiento y validación se sostienen sobre tres repositorios clínicos complementarios. La unificación de estas bases permite mitigar el sesgo inter-hospitalario y evaluar el algoritmo tanto en ventanas estáticas como en entornos dinámicos (Holter).

Base de Datos	Derivaciones	Frecuencia ($f_s$)	Aporte principal al proyecto y justificación
PTB-XL	12 derivaciones (clínicas estándar)	100 Hz / 500 Hz	Base de control principal. Aporta un volumen masivo de casos para clase normal (NORM). Incluye anotaciones granulares para bloqueos de rama completos (CRBBB, CLBBB) e incompletos (IRBBB, ILBBB), que se consolidan en LBBB/RBBB para mantener consistencia con el resto del dataset combinado.
CPSC 2018	12 derivaciones (longitud variable)	500 Hz	Introduce variabilidad poblacional masiva (recopilada en 11 hospitales distintos). Su inclusión es crítica para expandir las clases minoritarias (LBBB/RBBB), mitigar el sobreajuste (overfitting) de entorno y validar la capacidad de generalización del modelo frente a distintos equipos de adquisición.
Chapman-Shaoxing	12 derivaciones	500 Hz	Uno de los repositorios abiertos más extensos de arritmias (45.151 registros), con etiquetado sistemático de LBBB y RBBB. Es la base que más volumen aporta al proyecto, elevando sustancialmente la representación de bloqueos de rama en el dataset combinado y permitiendo evaluar la generalización del modelo sobre una población clínica independiente.

📥 Adquisición de Datos

Debido a su gran volumen, los conjuntos de datos no están incluidos en este repositorio. Para replicar este entorno, es necesario descargar los registros de forma externa en formato estándar de PhysioNet (.mat para señales digitales crudas y .hea para metadatos y etiquetas diagnósticas).

Enlaces de descarga originales:

• PTB-XL Database - PhysioNet
• China Physiological Signal Challenge 2018 - Kaggle
• Chapman-Shaoxing Database

Nota de preprocesamiento: Debido a la heterogeneidad en las frecuencias de muestreo originales (100 Hz, 257 Hz, 500 Hz), el pipeline de datos incluye un bloque inicial de resampling paramétrico para unificar la resolución temporal de las señales antes de alimentar la red neuronal. Se recomienda el uso de la librería oficial wfdb en Python para la lectura de los registros.

final-bird-ecg-detection/ ├── data/ │ ├── raw/ # Datasets crudos descargados (PTB-XL, CPSC2018, Chapman-Shaoxing) │ └── processed/ │ ├── metadata/ # Tablas de etiquetas (maestra, limpia) │ ├── signals/ # Señales filtradas y resampleadas a 100 Hz (.npy) │ ├── intermediate/ # Matriz de features sin balancear/dividir │ ├── features_trainval.csv # Set de entrenamiento + validación (80%) │ └── features_test.csv # Set de holdout final (20%) ├── models/ # Modelos entrenados (.joblib): RF baseline, MLP baseline, RF tuneado ├── notebooks/ # Notebooks de exploración │ ├── reports/ # Matrices de confusión y reporte final de evaluación ├── src/ # Código fuente del pipeline (paquete importable) │ ├── init.py │ ├── config.py # Rutas centralizadas del proyecto │ ├── dataset_consolidator.py # Etapa 1: unifica etiquetas de las 3 bases │ ├── preprocess_signals.py # Etapa 2: filtrado, resampleo y control de calidad │ ├── pan_tompkins.py # Detección de QRS multi-derivación (consenso) │ ├── qrs_segmentation.py # Delimitación de complejos QRS por amplitud │ ├── features.py # Extracción de las 51 características (morfológicas, PSD, wavelet) │ ├── extract_features.py # Etapa 3: orquesta la extracción sobre todo el dataset │ ├── dataset_splitter.py # Etapa 4: balanceo (undersampling) y split estratificado │ ├── train_rf.py # Etapa 5: baseline Random Forest │ ├── train_mlp.py # Etapa 6: baseline MLP │ ├── tune_rf.py # Etapa 7: tuning conservador de Random Forest (GridSearchCV) │ ├── evaluate_test.py # Etapa 8: evaluación final sobre el holdout │ └── data_loader.py # Carga de registro únicos para la aplicación del pipeline de forma individual ├── main.py # Orquestador: corre las 8 etapas del pipeline en orden ├── requirements.txt └── README.md

Interfaz Gráfica (GUI)

El proyecto incluye una aplicación de escritorio intuitiva construida con PyQt5 y Matplotlib para la inspección clínica, inferencia por lotes y auditoría del modelo.

Cómo ejecutarla

1. Asegurate de tener el modelo entrenado en la carpeta models/. Si no existe, generalo desde la terminal con:

   python main.py --only 7

2. Inicia la interfaz desde la raíz del repositorio:

   python gui.py

---

Guía rápida de las pestañas disponibles

• 1️- Registro individual:

  • Carga flexible: Lee archivos crudos WFDB (.hea), preprocesados (.npy) o busca directamente por ID del catálogo (ej. JS39226).
  • Diagnóstico visual: Muestra la clase predicha (NORM 🟢, LBBB 🔴, RBBB 🔵) y su nivel de confianza, verificando el acierto si el registro dispone de etiqueta real.
  • Análisis de señal: Grafica la derivación V1 con sombreado adaptativo sobre los complejos QRS detectados y permite inspeccionar una tabla colapsable con las 51 features extraídas.

• 2️- Análisis por lote:

  • Inferencia masiva: Procesa directorios enteros de archivos .hea o listas de IDs cargadas mediante un archivo CSV.
  • Monitoreo y exportación: Cuenta con barra de progreso en tiempo real, tabla de resultados exportable directamente a .csv e histograma con la distribución de diagnósticos del lote.

• 3️- Evaluar algoritmo:

  • Auditoría rápida: Carga un set de features con etiquetas verdaderas (ej. features_test.csv) para medir el rendimiento del modelo en segundos.
  • Métricas completas: Despliega el reporte de clasificación de scikit-learn (Precision, Recall, F1-Score), el área AUC-ROC (macro) y grafica la matriz de confusión.