---
tags:
- ml-intern
---
# 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

```bash
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

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

<!-- ml-intern-provenance -->
## Generated by ML Intern

This model repository was generated by [ML Intern](https://github.com/huggingface/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.