Datasets externos

Los ejemplos de Jano deberían ser reproducibles sin commitear datasets pesados en Git. El repositorio versiona metadata y código de descarga, mientras que los archivos descargados quedan siempre locales bajo data/raw/.

El directorio data/ está ignorado intencionalmente por Git.

Registry

La metadata vive en datasets/registry.json. Cada entrada registra la URL de origen, página fuente, nota de licencia o términos, path local esperado, tipo de tarea, columna temporal y target sugerido.

El registry actual incluye:

  • bike_sharing_hourly para ejemplos chicos de regresión y walk-forward.

  • bts_airline_2024_01 para costos ordinales de demoras y retraining.

  • nyc_tlc_yellow_2024_01 para ejemplos grandes con Parquet y benchmarks.

  • household_power para granularidad temporal por minuto.

  • rossmann_store_sales como gold example para comparar split aleatorio, holdout cronológico, simulación walk-forward y policies de retraining.

Descarga local

Listar datasets disponibles:

python scripts/download_dataset.py --list

Descargar un dataset sin guardarlo en Git:

python scripts/download_dataset.py bike_sharing_hourly --extract

Algunos datasets requieren credenciales del proveedor. Rossmann está alojado en Kaggle, por lo que primero hay que configurar la Kaggle CLI y luego correr:

python scripts/download_dataset.py rossmann_store_sales --extract

Por defecto se guarda debajo de data/raw/. Podés cambiar esa ubicación:

python scripts/download_dataset.py nyc_tlc_yellow_2024_01 --data-root /tmp/jano-data

Gold example

El notebook Rossmann es el ejemplo end-to-end recomendado:

jupyter notebook notebooks/rossmann_temporal_validation.ipynb

Demuestra:

  • por qué un split aleatorio puede responder la pregunta temporal equivocada,

  • cómo un holdout cronológico mejora el baseline pero sigue dando una sola foto,

  • cómo plan() expone la geometría de folds antes de entrenar,

  • cómo WalkForwardRunner ejecuta el mismo modelo en varias fechas simuladas de despliegue,

  • cómo comparar policies de retraining sobre la misma geometría temporal.

Si no hay credenciales de Kaggle, el notebook usa un fallback determinístico similar a Rossmann. Eso lo mantiene ejecutable offline sin ocultar que el camino principal es el dataset real.

Política

  • Commitear metadata, ejemplos y scripts de descarga.

  • No commitear CSV, ZIP, Parquet ni archivos de cache descargados.

  • Mantener notebooks ejecutables descargando o leyendo archivos locales desde data/raw/.

  • Mantener tests automatizados independientes de la red; usar fixtures sintéticas o descargas locales mockeadas.

  • Marcar cualquier chequeo futuro con datos reales como opcional o external-data.