feat(eda): series temporales + rigor anti-data-mining + PDF movil + /eda + benchmark issues

Bloque del grupo eda (sesion ausente EDA-benchmark):
- 8 funciones nuevas: adf_kpss_stationarity, acf_pacf, stl_decompose, to_returns,
  fdr_correction, suggest_reexpression, exploratory_caveats, render_eda_pdf
- integracion: profile_table (run_series, emit_pdf), association_matrix (FDR Benjamini-Hochberg),
  render_eda_markdown (secciones series/reexpresion/caveats)
- slash commands /eda y /capitulos
- issues 0173-0177: mejoras del /eda derivadas del benchmark sobre 12 datasets reales
  (outlier_pct x100, periodo estacional, FK inference, render models, tipos id-like)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Egutierrez
2026-06-29 03:34:01 +02:00
parent 02301aaed3
commit 7ac69ab4fb
33 changed files with 3995 additions and 51 deletions
@@ -0,0 +1,77 @@
---
name: exploratory_caveats
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: pure
signature: "def exploratory_caveats(profile: dict) -> dict"
description: "Genera las advertencias que recuerdan que un EDA es EXPLORATORIO (genera hipotesis), no confirmatorio. Inspecciona un TableProfile del grupo eda y devuelve solo los caveats que aplican a lo calculado: correlacion!=causalidad, overfitting in-sample, p-values no son confirmacion, comparaciones multiples, outliers!=errores, muestra pequena, datos faltantes. El caveat general va siempre. Pura."
tags: [eda, exploratory, caveats, hypotheses, overfitting, correlation-causation, p-values, tukey, lopez-de-prado, python]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
- name: profile
desc: "TableProfile dict del grupo eda. Se leen defensivamente `correlations` (pares), `models` (pca/kmeans/outliers/normality), `columns` (sub-bloques `numeric` con n_outliers/outlier_pct y `trend` con p_value), `n_rows`, `null_cell_pct` y `all_null_cols`. Cualquier clave puede faltar."
output: "dict con `n` (numero de caveats), `caveats` (lista de {id, topic, message, reference} empezando por el general `exploratory_nature`) y `note` (vacio en caso normal; mensaje si el perfil esta vacio y solo se devuelve el caveat general). Nunca lanza excepcion."
tested: true
tests: ["test_perfil_vacio_solo_caveat_general", "test_none_no_lanza_y_da_general", "test_caveat_general_siempre_primero", "test_correlaciones_disparan_causalidad_y_overfitting", "test_dos_o_mas_pares_disparan_comparaciones_multiples", "test_modelos_disparan_overfitting_y_pvalues", "test_outliers_por_columna_disparan_caveat", "test_outliers_multivariantes_disparan_caveat", "test_trend_pvalue_dispara_caveat_pvalues", "test_muestra_pequena_dispara_caveat", "test_muestra_grande_no_dispara_small_sample", "test_muchos_faltantes_disparan_missing_data", "test_columnas_all_null_disparan_missing_data", "test_pocos_faltantes_no_disparan_missing_data", "test_estructura_de_cada_caveat"]
test_file_path: "python/functions/datascience/exploratory_caveats_test.py"
file_path: "python/functions/datascience/exploratory_caveats.py"
---
## Ejemplo
```python
from datascience import exploratory_caveats
profile = {
"n_rows": 5000,
"correlations": {"pairs": [
{"a": "precio", "b": "ventas", "value": 0.82},
{"a": "precio", "b": "margen", "value": -0.61},
]},
"models": {"pca": {"explained": [0.6, 0.3]}, "normality": {"precio": {"is_normal": False}}},
"columns": [{"name": "precio", "numeric": {"n_outliers": 4, "outlier_pct": 0.8}}],
}
out = exploratory_caveats(profile)
out["n"] # -> 6
[c["id"] for c in out["caveats"]]
# -> ['exploratory_nature', 'correlation_not_causation', 'in_sample_overfitting',
# 'p_values_not_confirmation', 'multiple_comparisons', 'outliers_not_errors']
# Perfil vacio -> solo la advertencia general.
exploratory_caveats({})["caveats"][0]["id"] # -> "exploratory_nature"
```
## Cuando usarla
Al cerrar un EDA, antes de entregar el reporte o de tomar decisiones sobre lo que
muestra. Convierte la disciplina exploratoria (Tukey: el EDA da hipotesis, no
conclusiones) en una lista accionable de advertencias adaptada a lo que realmente se
calculo en ese perfil. Pensada para inyectar una seccion "Advertencias / esto es
exploratorio" en el markdown de un reporte EDA, o para que un agente recuerde no
tratar una correlacion o una "significancia" como confirmacion. NO la uses para
calcular estadisticos: solo razona sobre el contenido de un TableProfile ya hecho.
## Gotchas
- Es **pura**: no recalcula nada, solo decide que advertencias aplican a partir de
las claves presentes en el `profile`. Si una fase del EDA no se corrio (p.ej. sin
`models`), su caveat no aparece — es deliberado.
- El caveat `exploratory_nature` (general) va SIEMPRE, incluso con perfil vacio o
`None` (en ese caso `note` lo avisa). No lanza excepcion ante entradas raras.
- `correlations` se tolera como lista de pares o como dict con `pairs`/`strongest`
(mismo shape que consume `render_eda_markdown`). Un solo par dispara
`correlation_not_causation` + `in_sample_overfitting`; >=2 anaden ademas
`multiple_comparisons`.
- Umbrales: muestra pequena si `n_rows < 30`; faltantes notables si
`null_cell_pct > 0.2` (fraccion) o si hay `all_null_cols`. Son convenciones
prudentes, ajustables si el caller lo necesita (recomputando sobre el mismo
profile).
- `null_cell_pct` se asume fraccion 0-1 (como en el resto del grupo eda). Si tu
pipeline lo guarda como porcentaje 0-100, el umbral se dispara casi siempre.