fn_registry/.claude/commands/eda.md

description

description
EDA (exploratory data analysis) de una tabla o de una base entera con el grupo `eda` del registry. Perfila, escribe el report (JSON + Markdown + PDF móvil) y monta un analysis Jupyter lanzado en el navegador colaborativo y ejecutado en vivo por Claude.

/eda — Exploratory Data Analysis con el grupo eda

Cuando Enmanuel pide un EDA ("hazme un EDA de X", "analiza esta tabla", "qué hay en estos datos"), no escribas análisis inline: usa el grupo de capacidad eda del registry, escribe los reports y monta el analysis Jupyter en su navegador colaborativo, ejecutando las celdas tú mismo en vivo. Respeta la memoria eda-workflow-registry y la regla .claude/rules/notebook_collaboration.md.

Página madre del grupo: docs/capabilities/eda.md (léela primero para cargar el cluster entero).

Uso

/eda /ruta/datos.duckdb tabla                  # EDA de una tabla DuckDB
/eda /ruta/datos.csv                           # CSV/Parquet → cargar a DuckDB y perfilar
/eda postgresql://user:pass@host:5432/db tabla # EDA de una tabla PostgreSQL (backend="postgres")
/eda /ruta/datos.duckdb --all                  # EDA de TODA la base (todas las tablas + FK + join graph)
/eda /ruta/datos.duckdb ventas --series --pdf  # con análisis de serie temporal + PDF móvil

$ARGUMENTS lleva la fuente y, opcionalmente, la tabla y flags. Interpreta:

• Fuente: ruta a .duckdb/.csv/.parquet, o un DSN PostgreSQL (postgresql://... o postgres://...).
• Tabla: nombre de la tabla. Si no se da y la fuente es un único archivo CSV/Parquet, usa su nombre base. Si se pide "toda la base" / --all, usa profile_database.
• Flags (actívalos según lo que pida el usuario; pregunta solo si es ambiguo y costoso):
  • --models → run_models=True (PCA/KMeans/IsolationForest/normalidad).
  • --llm → run_llm=True (1 call LLM sobre el perfil agregado).
  • --series → run_series=True (estacionariedad ADF+KPSS, ACF/PACF, STL, retornos por columna numérica).
  • --pdf → emit_pdf=True (PDF A5 vertical legible en móvil).

Por defecto, para un EDA "completo" cuando el usuario no especifica, activa run_models, run_series y emit_pdf; deja run_llm para cuando lo pida o cuando interese la interpretación semántica (es la única parte que gasta tokens del modelo).

Reglas duras

1. Registry-first: invoca las funciones del grupo eda, no reescribas lógica de perfilado ni de gráficos inline (regla registry_first.md).
2. CSV/Parquet/Excel entran cargándolos antes a DuckDB (read_csv_auto/read_parquet/read_xlsx) — DuckDB es el motor por defecto. No traigas la tabla entera a RAM.
3. Secretos: si la fuente es un DSN PostgreSQL con credenciales, NO las imprimas en los reports ni en el notebook; resuélvelas vía resolve_pg_dsn/pass cuando aplique.
4. El report es un artefacto local: vive en reports/ (gitignored), no se sube a Gitea ni se versiona. Compartir = pasar la ruta (regla reports.md).
5. Entrega las 4 salidas: JSON sidecar + Markdown + PDF móvil + notebook Jupyter colaborativo ejecutado en vivo.

Paso 1 — Perfilar y escribir los reports

Una tabla (caso normal):

PYTHONPATH=python/functions python/.venv/bin/python3 - <<'PYEOF'
from pipelines.profile_table import profile_table
r = profile_table(
    "/ruta/datos.duckdb", "ventas",
    run_models=True, run_series=True, emit_pdf=True, run_llm=False,
)
print("status:", r["status"])
print("md:   ", r["report_md_path"])
print("json: ", r["report_json_path"])
print("pdf:  ", r["pdf_path"])
PYEOF

Una base entera (todas las tablas + relaciones FK):

PYTHONPATH=python/functions python/.venv/bin/python3 - <<'PYEOF'
from pipelines.profile_database import profile_database
r = profile_database("/ruta/datos.duckdb")
print(r["db_profile"]["join_graph"]["mermaid"])
PYEOF

Lee el Markdown resultante y resume a Enmanuel lo esencial: forma, calidad, correlaciones fuertes (ya corregidas por FDR), series no estacionarias, transformaciones sugeridas y avisos exploratorios.

Paso 2 — Notebook Jupyter colaborativo, ejecutado en vivo por Claude

Sigue la memoria eda-workflow-registry y la regla notebook_collaboration.md:

1. Genera el notebook con build_eda_notebook (mismo perfil de la tabla):

   PYTHONPATH=python/functions python/.venv/bin/python3 - <<'PYEOF'
   from datascience import build_eda_notebook
   build_eda_notebook("/ruta/datos.duckdb", "ventas",
                      "analysis/eda_ventas/notebooks/01_eda.ipynb", run_models=True)
   PYEOF
   

   (o crea un analysis dedicado con fn run init_jupyter_analysis eda_ventas duckdb y escribe el notebook dentro de notebooks/).

2. Confirma que hay Jupyter colaborativo activo con jupyter_discover (o lánzalo con el run-jupyter-lab.sh del analysis) y ábrelo en el navegador colaborativo para que Enmanuel lo vea en vivo.

3. Ejecuta tú las celdas (no se las dejes para que las corra él): usa las funciones del dominio notebook (jupyter_exec append+execute / jupyter_read) descritas en notebook_collaboration.md, o el MCP jupyter si está conectado en la sesión del analysis. Ejecuta de arriba a abajo, comenta cada bloque relevante y deja el notebook navegable.

Notas

• El TableProfile lleva ahora, además del perfilado base y las correlaciones con FDR: series (por columna numérica, con run_series), reexpression por columna numérica (escalera de Tukey) y caveats (siempre, avisos exploratorios). El Markdown y el PDF renderizan estas secciones automáticamente cuando están presentes.
• El PDF (emit_pdf) está pensado para leerse en el móvil (A5 vertical, tipografía grande, gráficos Tufte). Se escribe junto al Markdown en reports/.
• run_series ordena por la primera columna datetime si existe; si no, por el orden físico de filas. Necesita ≥8 puntos válidos por columna.
• Fuentes: DuckDB (CSV/Parquet/Excel cargados antes) y PostgreSQL (backend="postgres"). profile_database (multi-tabla + FK) es solo DuckDB por ahora.