StationarityToolkit: Comprehensive Time Series Stationarity Analysis in Python

El artículo presenta `StationarityToolkit`, una biblioteca de Python que ofrece un análisis integral de la estacionariedad en series temporales mediante la ejecución de 10 pruebas estadísticas en tres categorías (tendencia, varianza y estacionalidad) para proporcionar diagnósticos detallados y recomendaciones accionables en lugar de simples veredictos binarios.

Lo esencial

Imagina que tienes un orquestador de música (un analista de datos) que intenta predecir el futuro basándose en una canción que está sonando (tus datos). Para que la predicción sea buena, la canción debe tener un ritmo constante y predecible. Si la música cambia de tempo, se vuelve más fuerte o más suave de repente, o si tiene un coro que se repite de forma caótica, el orquestador se confundirá y fallará.

En el mundo de las estadísticas, a esa "canción constante" le llamamos estacionariedad.

Aquí te explico qué hace StationarityToolkit (el kit de herramientas de estacionariedad) usando analogías sencillas:

1. El Problema: El "Detective" que solo tiene una lupa

Antes de este programa, si un investigador quería saber si su "canción" (datos) era estable, tenía que usar herramientas separadas.

• Si quería ver si el ritmo cambiaba, usaba una lupa.
• Si quería ver si el volumen subía y bajaba, usaba otra.
• Si quería ver si había un coro repetitivo, usaba una tercera.

El problema es que a veces una lupa dice "todo está bien" y la otra dice "¡Peligro!". Además, arreglar un problema (como bajar el volumen) a veces crea otro nuevo (como cambiar el ritmo). Los investigadores tenían que hacer esto manualmente, paso a paso, y era fácil cometer errores o perderse detalles importantes.

2. La Solución: El "Médico General" de los Datos

StationarityToolkit es como un médico general muy inteligente que llega con una maleta completa. En lugar de pedirte que elijas qué prueba hacer, él hace todo el chequeo completo de una sola vez.

Este "médico" tiene 10 pruebas diferentes divididas en tres áreas:

1. La Tendencia (El ritmo): ¿La canción va subiendo o bajando constantemente? (Pruebas de tendencia).
2. La Variación (El volumen): ¿La música se vuelve más ruidosa o impredecible con el tiempo? (Pruebas de varianza).
3. La Estacionalidad (El coro): ¿Hay patrones que se repiten cada semana, mes o año? (Pruebas de estacionalidad).

3. ¿Qué hace diferente a este "Médico"?

• No solo dice "Sí" o "No": En lugar de darte una respuesta binaria como "Está bien" o "Está mal", te da un diagnóstico detallado. Te dice: "Oye, detecté que el volumen sube y baja (varianza inestable), así que podrías intentar aplicar un truco matemático llamado 'Box-Cox' para suavizarlo".
• Es un detective de frecuencias: Si le das datos con fechas, el programa adivina automáticamente si tus datos son diarios, mensuales o anuales, y busca los patrones repetitivos adecuados sin que tú tengas que decirle nada.
• El ciclo de "Probar, Arreglar, Volver a Probar": Imagina que arreglas un coche. A veces, al cambiar una pieza, otra se rompe. Este programa te permite hacer el cambio, y luego volver a correr todas las pruebas inmediatamente para ver si arreglaste el problema o si creaste uno nuevo.

4. La Filosofía: "Te muestro el mapa, tú conduces"

Una de las cosas más importantes de este programa es que no decide por ti.

• Algunos programas antiguos intentaban arreglar los datos automáticamente (como un robot que pinta el coche por ti), pero a veces el robot arruina la pintura.
• StationarityToolkit prefiere ser un copiloto experto. Te muestra el mapa completo, te dice dónde están los baches y te sugiere cómo evitarlos, pero tú (el investigador) tomas la decisión final sobre qué herramienta usar, porque entiende que cada "coche" (cada conjunto de datos) es único.

En resumen

StationarityToolkit es una caja de herramientas en Python que ayuda a científicos y analistas a entender si sus datos son estables antes de intentar predecir el futuro. En lugar de tener que buscar diez herramientas diferentes en diez estantes distintos, te da una sola caja que hace todo el trabajo sucio, te explica qué está mal con palabras sencillas y te ayuda a evitar errores comunes al limpiar tus datos.

Es como tener un mecánico de confianza que no solo repara tu coche, sino que te explica exactamente qué pieza falló y por qué, para que tú aprendas a conducir mejor en el futuro.

Resumen técnico

Resumen Técnico: StationarityToolkit

1. El Problema

La estacionariedad es una propiedad fundamental en el análisis de series temporales, donde las características estadísticas (tendencia, varianza, estacionalidad) deben permanecer constantes en el tiempo. Sin embargo, la no estacionariedad no es un fenómeno único; puede manifestarse como:

• Raíces unitarias o tendencias deterministas.
• Rupturas estructurales.
• Variabilidad de la varianza (inestabilidad, agrupamiento de volatilidad).
• Patrones estacionales estocásticos o deterministas.

Limitaciones actuales:

• Enfoque de prueba única: La mayoría de las herramientas actuales se centran en un solo tipo de prueba (ej. solo raíces unitarias), lo que lleva a diagnósticos incompletos. Una serie puede pasar una prueba pero fallar en otra.
• Falta de integración: Los practicantes deben ejecutar manualmente pruebas de diferentes bibliotecas (statsmodels, arch, scipy), interpretar resultados potencialmente contradictorios y decidir qué transformaciones aplicar.
• Riesgo de transformaciones incorrectas: Las transformaciones para corregir un tipo de no estacionariedad (ej. diferenciación para tendencias) pueden introducir o exacerbar otros tipos (ej. inestabilidad de varianza). Sin un flujo de trabajo iterativo de "prueba-transformar-reprobar", es difícil verificar si el preprocesamiento ha logrado la estacionariedad real.

2. Metodología y Diseño del Software

StationarityToolkit es una biblioteca de Python pura diseñada para cerrar esta brecha mediante un enfoque integral y diagnóstico.

• Arquitectura:

  • Dependencias: Se basa en numpy, pandas, scipy, arch y statsmodels.
  • Estructura modular: Separa la implementación de pruebas (tests/), el formateo de resultados (results.py) y el punto de entrada principal (toolkit.py).
  • Filosofía de diseño: Prioriza la transparencia sobre la prescripción. En lugar de automatizar transformaciones (lo cual se demostró problemático en versiones anteriores debido a la variabilidad de los datos), la herramienta se centra en proporcionar diagnósticos detallados para que el usuario tome decisiones informadas.

• Flujo de Trabajo:

  1. Inferencia automática de frecuencia: Requiere un índice de tipo datetime para inferir automáticamente la frecuencia de los datos (diaria, mensual, etc.).
  2. Ejecución de pruebas: Ejecuta 10 pruebas estadísticas en una sola llamada, divididas en tres categorías:
     • Tendencia (4 pruebas): Incluye ADF, KPSS, Phillips-Perron y Zivot-Andrews. Ejecutan variantes con y sin tendencia para distinguir entre raíces unitarias y tendencias deterministas.
     • Varianza (4 pruebas): Detectan inestabilidad de varianza y agrupamiento de volatilidad (incluyendo pruebas ARCH/GARCH).
     • Estacionalidad (2 pruebas): Detectan estacionalidad estocástica o determinista.
  3. Salida contextual: El sistema no solo devuelve un resultado binario (paso/fallo), sino que infiere los periodos estacionales adecuados basándose en la frecuencia inferida, eliminando la necesidad de especificación manual.

3. Contribuciones Clave

1. Pruebas Integrales por Defecto: Elimina la carga cognitiva de seleccionar qué pruebas ejecutar. Se ejecutan las 10 pruebas simultáneamente para asegurar que no se pierda información crítica.
2. Notas Accionables y Diagnósticas: Cada resultado incluye notas concisas sobre las advertencias de la prueba y sugerencias específicas (ej. "Raíz unitaria detectada: considerar diferenciación" o "Tendencia determinista detectada: estacionaria tras eliminar tendencia").
3. Detección de Estacionalidad Contextual: Automatiza la selección de los periodos de prueba (semanal, mensual, anual) según la frecuencia de los datos.
4. Reporte Dual: El método report() devuelve un DataFrame de pandas para análisis interactivo y opcionalmente genera un informe en Markdown para documentación.
5. Transparencia en las Limitaciones: El toolkit advierte explícitamente sobre las limitaciones de ciertas pruebas (ej. cómo Zivot-Andrews puede detectar "rupturas" en tendencias suaves o cómo ARCH puede activarse por autocorrelación), algo que las pruebas individuales suelen omitir.

4. Resultados y Rendimiento

• Eficiencia: La ejecución secuencial de todas las pruebas en una serie de 1000 filas toma menos de 2 segundos en hardware moderno.
• Validación: Las implementaciones se han validado contra bibliotecas establecidas (statsmodels, arch, scipy) y sobre datos sintéticos con propiedades conocidas.
• Disponibilidad: El paquete ha estado disponible públicamente en PyPI desde 2023 y cuenta con documentación completa, incluyendo ejemplos en Jupyter Notebooks (examples/detailed_usage.ipynb) que demuestran el uso en datos sintéticos y reales.

5. Significado e Impacto de la Investigación

StationarityToolkit aborda una brecha genuina en el ecosistema de Python al proporcionar la primera herramienta que integra la detección de no estacionariedad en las dimensiones de tendencia, varianza y estacionalidad en un solo flujo de trabajo.

• Impacto Científico: Su mayor valor reside en revelar efectos de contaminación cruzada (ej. cómo la diferenciación para eliminar la tendencia puede generar no estacionariedad en la varianza), un fenómeno que los enfoques de prueba única pasan por alto.
• Reproducibilidad: Al proporcionar notas detalladas sobre por qué se detectó un problema y qué transformaciones se sugieren, facilita la reproducibilidad de los estudios, permitiendo a los investigadores entender la lógica detrás de las decisiones de preprocesamiento.
• Aplicabilidad: Es una herramienta crítica para científicos de datos, economistas e investigadores que preparan datos para modelos ARIMA/SARIMA, análisis VAR, pruebas de causalidad de Granger o aplicaciones de aprendizaje automático, donde la estacionariedad mejora la generalización.

Nota sobre el uso de IA: El diseño central, la escritura de pruebas y el contenido del artículo fueron concebidos por el autor humano. La IA (Claude) se utilizó únicamente para refinar código, eliminar redundancias, mejorar nombres de variables, añadir docstrings y refinar la documentación, todo bajo la supervisión y validación final del autor humano.