Gastpm/sleep-apnea-shhs-v2

Detector de Apnea del Sueño v2 - Dataset SHHS

Descripción

Sistema completo de detección de apnea/hipopnea nocturna basado en señales de oximetría de pulso (SpO₂) y frecuencia cardíaca (HR) del dataset SHHS (Sleep Heart Health Study).

Características clave

• Arquitectura SOTA 2024-2026: TCN (Temporal Convolutional Network) dilatado multiescala + BiGRU + Temporal Self-Attention
• Manejo de desbalance masivo: Focal Loss (γ=2) + WeightedRandomSampler con oversampling de ventanas positivas
• Delay desaturación: Shift de etiquetas hacia atrás (60s) + ventanas asimétricas para capturar baseline y recuperación
• Split por paciente: Ninguna fuga de información entre entrenamiento/testeo
• Métricas clínicas completas: Sensibilidad, Especificidad, AUC-ROC, AUC-PR, Cohen's κ, AHI
• AHI por paciente: Estimación del Índice Apnea-Hipopnea (eventos/hora) para screening clínico

Arquitectura

Input: HR (1Hz) + SaO2 (1Hz) → (B, 2, 900) [15 min ventanas]

1. TCN Encoder (dilataciones 1,2,4,8)
   Conv1d-BN-ReLU → Residual blocks → (B, 256, T')

2. BiGRU (2 capas, hidden=128)
   Forward + Backward → (B, T', 256)

3. Temporal Self-Attention (4 heads)
   Lightweight attention → (B, T', 256)

4. Multi-scale Pooling
   GlobalAvgPool + GlobalMaxPool → (B, 512)

5. Classifier
   LayerNorm → Dropout → Linear(512→256→2)

Output: Logits binarios (Normal vs Apnea/Hipopnea)

Parámetros entrenables: ~3.1M

Requisitos

pip install -r requirements.txt

Estructura de datos esperada

Archivos .mat con las siguientes variables:

• HR: Frecuencia cardíaca (1 Hz), shape (N,) o (N,1)
• SaO2 o SaO2: Saturación de oxígeno (1 Hz, resolución 1%), shape (N,)
• Target03: Etiquetas (0=normal, !=0=apnea/hipopnea), shape (N,)
• OXStat: Calidad de señal (0=buena calidad, !=0=artefacto), shape (N,)

Uso

Entrenamiento

python train_sleep_apnea.py \
  --data_dir /ruta/a/archivos/mat \
  --output_dir /ruta/a/salida \
  --epochs 100 \
  --batch_size 32 \
  --lr 0.001 \
  --window_size 900 \
  --stride 60 \
  --seed 42

Inferencia / Evaluación

python inference_sleep_apnea.py \
  --data_dir /ruta/a/test/mat \
  --model_path /ruta/a/salida/best_model.pt \
  --output_dir /ruta/a/resultados \
  --threshold 0.5 \
  --batch_size 64

Salidas generadas

Archivo	Descripción
best_model.pt	Mejor modelo (según F1 en validación)
training_curves.png	Evolución de loss, accuracy, sensibilidad, especificidad
confusion_matrix.png	Matriz de confusión en test
roc_pr_curves.png	Curvas ROC y Precision-Recall
final_report.json	Métricas completas en formato JSON

Métricas reportadas

• Accuracy: Porcentaje de aciertos total
• Sensitivity (Recall): Tasa de detección de apneas/hipopneas (TPR)
• Specificity: Tasa de correcta identificación de normalidad (TNR)
• Precision: Precisión de las detecciones positivas
• F1-Score: Media armónica de precision y recall
• Cohen's Kappa: Concordancia ajustada por azar
• AUC-ROC: Área bajo curva ROC
• AUC-PR: Área bajo curva Precision-Recall (mejor para desbalance)
• AHI MAE/RMSE: Error en estimación de apneas por hora

Hiperparámetros clave

Parámetro	Default	Descripción
window_size	900	Tamaño ventana (15 min @ 1Hz)
stride	60	Solapamiento (1 min)
label_shift	60	Shift etiquetas para delay desaturación (60s)
focal_gamma	2.0	Factor focal loss
lr	1e-3	Learning rate AdamW
dropout	0.4	Regularización
patience	15	Early stopping (épocas sin mejora)

Referencias bibliográficas

1. TSCMamba (Ahamed & Cheng, 2024): Mamba + CWT multi-view. arXiv:2406.04419
2. Mamba Sleep Staging (Zhang et al., 2025): Bidirectional Mamba sin EEG. arXiv:2412.15947
3. TimeMIL (Chen et al., 2024): MIL para eventos raros. arXiv:2405.03140
4. Focal Loss (Lin et al., 2017): Pérdida para desbalance. ICCV 2017
5. TimesNet (Wu et al., NeurIPS 2022): Modelado 2D temporal. arXiv:2210.02186
6. SHHS Dataset: https://sleepdata.org/datasets/shhs

Generated by ML Intern

This model repository was generated by ML Intern, an agent for machine learning research and development on the Hugging Face Hub.

• Try ML Intern: https://smolagents-ml-intern.hf.space
• Source code: https://github.com/huggingface/ml-intern

Usage

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = 'Gastpm/sleep-apnea-shhs-v2'
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id)

For non-causal architectures, replace AutoModelForCausalLM with the appropriate AutoModel class.