Exploración de HMM para Series Temporales (TSST · P6)

Subtítulo: Forward, Viterbi y clasificación de patrones con hmmlearn

Propuesta de nombre del repo: exploracion-hmm-series-temporales
(alternativas: analisis-hmm-temporal, hmm-forward-viterbi, tsst-hmm-exploration)

Este repositorio documenta una exploración práctica de Modelos Ocultos de Markov (HMM) aplicada a series temporales bivariadas. Partimos de un cuaderno Jupyter y resolvemos los tres problemas clásicos de HMM (puntuación/verosimilitud, decodificación y entrenamiento) y cerramos con una tarea de clasificación de patrones temporales (tres tipos de “avería” simulada) usando hmmlearn.

Nota: no se modifica el código existente; este README explica claramente qué hace el cuaderno y cómo reproducirlo.

---

🧭 Objetivos de aprendizaje

• Comprender cómo los parámetros de un HMM (π, A y distribuciones de emisión) afectan su comportamiento.
• Implementar y entender el algoritmo Forward para calcular la verosimilitud P(X|λ).
• Implementar y entender Viterbi para obtener la secuencia de estados más probable.
• Entrenar HMMs con hmmlearn y clasificar secuencias comparando log‑likelihoods.
• Visualizar distribuciones de emisión (Gaussianas/GMM) y secuencias generadas por el modelo.

---

📂 Estructura del cuaderno (overview)

Parte 1 — Introducción a HMM

1. Definición del HMM con N=4 estados:
   • π: vector de probabilidades iniciales.
   • A: matriz de transición entre estados.
   • Emisiones: Gaussianas bivariadas (medias μ y covarianzas Σ).
2. Visualización de las distribuciones de emisión (contornos) usando scipy.stats.multivariate_normal y matplotlib.
3. Generación de secuencias con hmmlearn.hmm.GaussianHMM para observar trayectorias y observaciones sintéticas.
4. Comparativa de modelos:
   • HMM1: Gaussianas por estado.
   • HMM2: GMM (3 componentes) por estado (GMMHMM).
   • HMM3: left‑to‑right (Bakis), con estructura de transición restringida.
     Se comparan log‑verosimilitudes sobre la misma secuencia para ver qué modelo explica mejor los datos.

Parte 2 — Tres problemas clásicos

• 2.1 Puntuación (Scoring): implementación de Forward → log P(X|λ).
• 2.2 Decodificación: implementación de Viterbi → secuencia de estados S*.
• 2.3 Entrenamiento: nociones de estimación de parámetros (con hmmlearn se realiza vía fit).

Parte 3 — Clasificación de patrones temporales

• Caso: detección de estados de una máquina usando dos medidas normalizadas (vibración y velocidad).
• Datasets (CSV, uno por clase):
  • sin_averias.csv
  • fallo_componente.csv
  • uso_inapropiado.csv
• Entrenamiento: un HMM por clase (p.ej., GaussianHMM o GMMHMM), entrenado con las 10 secuencias de cada CSV.
• Inferencia: dada test.csv, se calculan las log‑verosimilitudes con .score(X) para cada modelo y se predice la clase con mayor log‑likelihood.

---

🧪 Funciones clave implementadas

Estas funciones aparecen en el cuaderno y constituyen la base “desde cero” de la parte teórica.

• Normalize(u) → Normaliza y devuelve (α, C); C permite trabajar en escala log acumulando log C_t.
• eval_Px_Z(x, B) → Evalúa P(x|Z=k) usando las Gaussianas (o GMM) del estado k (scipy.stats.multivariate_normal).
• Forward(X, A, π, B) → Algoritmo Forward; devuelve log P(X|λ).
• Viterbi(X, A, π, B) → Algoritmo de Viterbi; devuelve la ruta de estados más probable.

En la parte de modelado con librería se emplean clases de hmmlearn:

• hmm.GaussianHMM (emisiones Gaussianas)
• hmm.GMMHMM (emisiones como mezclas Gaussianas)
• (opcional) MultinomialHMM en escenarios discretos

---

🗃️ Datos

• Formato: CSV con dos columnas (p.ej., vibración, velocidad) y filas = tiempo.
• Ubicación: colóquelos en la misma carpeta que el cuaderno Jupyter para que pandas.read_csv(..., index_col=0) funcione sin cambios.
• Ficheros esperados:
  • sin_averias.csv, fallo_componente.csv, uso_inapropiado.csv (entrenamiento)
  • test.csv (evaluación)

Si trabajas en Google Colab, puedes subir los CSV con files.upload() (la celda está preparada en el cuaderno).

---

🛠️ Requisitos

• Python ≥ 3.9
• numpy, pandas, scipy, matplotlib
• scikit-learn
• hmmlearn

Instalación rápida con pip:

python -m venv .venv && source .venv/bin/activate   # (Windows: .venv\Scripts\activate)
pip install numpy pandas scipy matplotlib scikit-learn hmmlearn

---

▶️ Cómo reproducir

Opción A — Local (Jupyter Lab/Notebook)

1. Clona el repo y entra en la carpeta.
2. Crea/activa un entorno e instala dependencias (ver arriba).
3. Asegúrate de que los CSV están junto al cuaderno PR6_TSST.ipynb (o ajusta la ruta en las celdas de carga).
4. Abre el cuaderno y ejecuta las celdas en orden.

Opción B — Google Colab

1. Sube el cuaderno a Colab.
2. Ejecuta la celda con files.upload() (si está comentada, descoméntala).
3. Sube los CSV y continúa ejecutando en orden.

---

📊 Resultados esperados (a alto nivel)

• Contornos de densidad para las distribuciones de emisión de cada estado.
• Secuencias simuladas (estados y observaciones) para ver el comportamiento del HMM.
• Comparativa de log‑likelihoods entre HMM1/HMM2/HMM3 sobre la misma secuencia.
• Forward devolviendo el logaritmo de la verosimilitud; Viterbi devolviendo la ruta más probable.
• Clasificación: el HMM entrenado que maximiza .score(test) indica la clase predicha para test.csv.

Los valores numéricos concretos dependen de la semilla y los datos; el cuaderno imprime las puntuaciones para su inspección.

---

🧠 Qué se aprende

• A diseñar un HMM: fijar π, A, y elegir emisiones (Gaussiana vs GMM).
• A escalar probabilidades para evitar underflow (acumulando log C_t en Forward).
• A decodificar secuencias con Viterbi y entender diferencias frente a Forward.
• A entrenar HMMs y comparar modelos por verosimilitud para clasificación.

---

⚠️ Limitaciones y siguientes pasos

• Los HMM con Gaussianas/GMM suponen independencia condicional de la observación dado el estado; si no se cumple, el ajuste puede empeorar.
• La elección del número de estados y de componentes GMM requiere validación (BIC/AIC, validación cruzada).
• Trabajo futuro sugerido: comparar este enfoque con LSTM/RNN en la misma tarea para estudiar:
  • dependencia de largo plazo,
  • sensibilidad al tamaño de datos,
  • coste computacional y robustez al ruido.

---

📎 Créditos y licencia

Material académico basado en la práctica TSST - P6 (HMM). Uso con fines docentes. Si reutilizas fragmentos de código, cita este repositorio y hmmlearn.

---

English quick summary

This notebook is a hands‑on HMM exploration for time series: we implement Forward (likelihood), Viterbi (decoding), and train class‑specific HMMs with hmmlearn to classify sequences by maximum log‑likelihood. Repro steps and dependencies are listed above.