You can deploy this model and start earning money today!

Gastpm/
sleep-apnea-shhs-v2

Views

No views yet

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

bash

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

bash

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

TSCMamba (Ahamed & Cheng, 2024): Mamba + CWT multi-view. arXiv:2406.04419
Mamba Sleep Staging (Zhang et al., 2025): Bidirectional Mamba sin EEG. arXiv:2412.15947
TimeMIL (Chen et al., 2024): MIL para eventos raros. arXiv:2405.03140
Focal Loss (Lin et al., 2017): Pérdida para desbalance. ICCV 2017
TimesNet (Wu et al., NeurIPS 2022): Modelado 2D temporal. arXiv:2210.02186
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

python

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.