Reporte de Auditoría y Remediación

1. Resumen ejecutivo

Una auditoría de producción detectó 3 hallazgos que inflaban las métricas de pronóstico entre un 5% y un 15%. Se aplicaron 3 correcciónes quirúrgicas en commits separados. Posteriormente se realizó una segunda auditoría exhaustiva que revisó la totalidad del código de preprocesamiento, entrenamiento, evaluación y selección de modelos para verificar que no existen problemas residuales de data leakage ni overfitting.

2. Hallazgos originales y remediación

2.1 Hallazgo 1 — Future Leakage en _ajusta_negativos()

Problema

El método _ajusta_negativos() en transformer.py:178 utilizaba shift(-1) para acceder al valor de la semana siguiente y calcular una interpolación bidireccional (t-1 + t+1) / 2 para reemplazar incrementos negativos. Este cálculo se ejecutaba sobre el DataFrame completo antes del split train/test, lo que filtraba informacion futura hacia el pasado en la frontera del corte temporal.

Impacto

• Los valores negativos cercanos al cutoff de entrenamiento se corregían usando datos del periodo de test.
• Todos los modelos (Prophet, DeepAR, Ensemble, Stacking) entrenaban con datos contaminados.
• Las métricas de evaluación aparecían artificialmente mejores entre un 5% y un 10%.

Remediación

Se elimino shift(-1) por completo. La corrección ahora usa exclusivamente datos pasados con una media móvil retrospectiva de 3 semanas, agrupada por ["Padecimiento", "Entidad"]:

-  prev_val = self.df[columna].shift(1)
-  next_val = self.df[columna].shift(-1)    # LEAKAGE: mira al futuro
-  extrap = (prev_val + next_val) / 2.0

+  prev3_mean = self.df.groupby(["Padecimiento", "Entidad"])[columna].transform(
+      lambda s: s.shift(1).rolling(window=3, min_periods=1).mean()
+  )

El patrón shift(1).rolling(3) garantiza que solo se utilizan valores de las 3 semanas anteriores, sin incluir la semana actual ni futuras.

Tests agregados

• test_ajusta_negativos_no_usa_futuro — Modifica el valor después de un negativo y verifica que la corrección no cambia (prueba de fuego anti-leakage).
• test_ajusta_negativos_respeta_grupos — Verifica que un negativo en entidad B no utiliza valores de entidad A.

Commit: 2fc4b620 — fix(data): eliminar future leakage en _ajusta_negativos

2.2 Hallazgo 2 — OOF con ventana unica en Stacking

Problema

StackingMetaLearner.fit_oof() utilizaba un único split temporal con oof_cutoff="2024-01-01", generando aproximadamente 52 filas de validación OOF. Los pesos Ridge se optimizaban para un solo régimen temporal, haciendolos frágiles ante cambios de tendencia, estacionalidad o eventos atipicos.

Impacto

• Los pesos del meta-learner podían sobreajustarse al régimen de 2024.
• Si un experto era bueno en 2024 pero malo en 2023, recibia un peso inflado.
• Las métricas del Stacking se inflaban entre un 5% y un 8%.

Remediación

Se implementó expanding-window OOF con múltiples folds:

1. Nuevo método _compute_oof_folds() que distribuye N cutoffs equidistantes entre (oof_cutoff - 18 meses) y oof_cutoff.
2. fit_oof() ahora itera sobre los folds, entrena copias independientes de los expertos (copy.deepcopy) en cada fold de entrenamiento, predice el fold de validación, y concatena todas las predicciones OOF.
3. Ridge se entrena sobre el conjunto concatenado de todos los folds, produciendo pesos que ven múltiples régimenes temporales.
4. Fallback automático a pesos iguales (1/N) si no hay folds validos.

Configuración

# config/models/stacking.yaml
stacking:
  oof_n_folds: 4            # Numero de folds expanding-window
  oof_min_train_weeks: 104  # Minimo de semanas para cada fold de entrenamiento

Tests agregados

• test_expanding_window_multiple_folds — Serie larga (350 semanas), verifica que los expertos se entrenan múltiples veces y los pesos suman ~1.0.
• test_fallback_datos_insuficientes — Serie corta (50 semanas), verifica que retorna pesos iguales.

Commit: 73f8c67b — feat(stacking): expanding-window OOF para meta-learner

2.3 Hallazgo 3 — Residuos In-Sample en Ensemble

Problema

EnsembleForecaster._fit_xgboost() calculaba los residuos de Prophet como y - prophet.predict(train), es decir, residuos in-sample. Dado que Prophet ya ha visto los datos de entrenamiento, sus predicciones in-sample son optimistamente buenas. XGBoost aprendia a corregir errores mas pequeños de los que realmente encontraria en producción.

Impacto

• XGBoost sub-corrigia en producción porque sus features de entrenamiento tenian residuos artificialmente pequeños.
• Las métricas del Ensemble se inflaban entre un 8% y un 15%.

Remediación

Se creo un nuevo módulo oof_residuals.py con la función generate_oof_residuals() que implementa expanding-window CV para Prophet:

1. Divide train_data en K=3 folds expanding-window.
2. Para cada fold, crea un Prophet temporal (no toca self._prophet), lo entrena en fold_train, y predice fold_val.
3. Calcula residuos OOF = y_real - yhat_prophet_oof, que son realistas porque Prophet no ha visto los datos de validación.
4. Construye features XGBoost usando la historia de fold_train para los lags.
5. Concatena features y residuos de todos los folds para entrenar XGBoost.

Se mantiene retrocompatibilidad: oof_residual_folds=0 activa el modo legacy (in-sample).

Configuración

# config/models/ensemble.yaml
oof_residual_folds: 3  # 0 = legacy in-sample

Tests agregados

• test_oof_residuals_backward_compatible — Con oof_residual_folds=0, el flujo es idéntico al legacy.
• test_oof_residuals_uses_oof_when_enabled — Con oof_residual_folds=3, se invoca generate_oof_residuals().
• test_oof_residuals_empty_fallback — Datos insuficientes, fallback automático a in-sample.

Commit: 66410259 — feat(ensemble): residuos out-of-fold para XGBoost

3. Segunda auditoría exhaustiva

Tras aplicar las 3 correcciónes, se realizó una auditoría completa de todo el pipeline de datos, entrenamiento, evaluación y selección de modelos. Se revisaron 25 archivos en busca de:

• Uso de datos futuros para transformar o entrenar (look-ahead bias)
• Splits train/test aleatorios en lugar de temporales
• Validación cruzada no temporal
• Features calculados con datos del periodo de evaluación (target leakage)
• Residuos in-sample usados para entrenamiento
• Métricas calculadas sobre datos vistos durante entrenamiento
• Hiperparámetros tunados con informacion del test set

3.1 Componentes auditados y resultado

3.2 Observaciones menores (corregidas)

Las 3 observaciones menores fueron corregidas en el commit 3fb29aec.

-  feats["roll_4"] = y_series.rolling(4).mean()
+  shifted = y_series.shift(1)
+  feats["roll_4"] = shifted.rolling(4).mean()

-  tmp["_naive_diff"] = tmp.groupby(grp)["y_real"].diff().abs()
+  tmp["_naive_diff"] = tmp.groupby(grp)["y_real"].diff(52).abs()

3.3 Decisiones intencionales documentadas

4. Resumen de cambios por archivo

5. Validación cruzada temporal: antes vs después

5.1 Disciplina temporal por modelo

5.2 Diagrama de flujo temporal

Datos crudos
    |
    v
[Preprocesamiento] --- shift(1).rolling(3) solo datos pasados
    |
    v
[Split temporal] --- cutoff fijo por config (2025-01-01)
    |
    +--- train_data (< cutoff)
    |       |
    |       +--- [Prophet CV] TimeSeriesSplit, N folds temporales
    |       +--- [DeepAR CV]  TimeSeriesSplit, multi-serie
    |       +--- [Ensemble]   XGB tuner (TimeSeriesSplit) + OOF residuos (3-fold)
    |       +--- [Stacking]   Expanding-window OOF (4-fold) para Ridge
    |
    +--- test_data (>= cutoff)
            |
            v
        [Evaluacion] --- metricas sobre datos NO vistos durante entrenamiento

6. Estado de la suite de tests

6.1 Desglose de tests nuevos

7. Conclusiones y recomendaciones

7.1 Estado actual

El pipeline de EpiForecast-MX cumple las mejores prácticas de MLOps para series de tiempo tras la remediación de los 3 hallazgos críticos:

• Sin future leakage: Todas las transformaciónes de datos usan exclusivamente datos pasados.
• Sin overfitting en meta-learner: Los pesos del Stacking se estiman con expanding-window OOF sobre múltiples régimenes temporales.
• Sin sesgo optimista en residuos: XGBoost del Ensemble entrena con residuos out-of-fold realistas.
• Splits temporales correctos: Todos los modelos usan cutoffs temporales, nunca splits aleatorios.
• CV temporal en tuning: TimeSeriesSplit en Prophet, DeepAR y Ensemble.

7.2 Próximos pasos recomendados

1. Re-entrenar Prophet, Ensemble y Stacking con los fixes aplicados y comparar métricas antes/después.
2. Ejecutar make compare-metrics para generar la comparativa Excel con las nuevas métricas.
3. Regenerar make tableau para actualizar el dashboard con MASE corregido.

7.3 Items NO requeridos

• No re-entrenar DeepAR: El modelo DeepAR no fue afectado por los hallazgos 2 y 3. El hallazgo 1 (preprocesamiento) requiere re-entrenamiento, pero DeepAR es lento y puede programarse por separado.
• No modificar el patrón train-on-full-serie: Es una decisión de diseño documentada e intencional para maximizar la calidad de pronóstico en producción.