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 legacy de render_eda_pdf, legible en móvil).
  • --legacy-only → emite SOLO el PDF legacy (sin AutomaticEDA), para casos en que solo se quiera el PDF rápido.

Por defecto, un EDA completo emite SIEMPRE el informe AutomaticEDA en sus dos formatos: PDF (A5 móvil) Y PPTX (16:9 para compartir) con los 11 capítulos poblados (portada, overview, distribuciones, calidad, correlaciones, modelos, series, geoespacial, agregación, interpretación LLM). Usa el pipeline render_automatic_eda (o profile_table(emit_automatic=True)), que activa run_models y run_series para que los capítulos de modelos/series/geoespacial/agregación salgan poblados. Deja run_llm para cuando el usuario lo pida o interese la interpretación semántica + narrativa por capítulo (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 salidas: el informe AutomaticEDA PDF + PPTX (siempre, con render_automatic_eda / emit_automatic=True) + (opcional) JSON sidecar + Markdown + PDF legacy + notebook Jupyter colaborativo ejecutado en vivo. Comparte las rutas de PDF y PPTX.

Paso 1 — Perfilar y escribir los reports

Una tabla (caso normal):

PYTHONPATH=python/functions python/.venv/bin/python3 - <<'PYEOF'
from pipelines.render_automatic_eda import render_automatic_eda
# Informe AutomaticEDA COMPLETO one-shot: perfil + ctx (datos crudos) + PDF + PPTX
# con los 11 capítulos poblados (clusters pintados, evolución temporal, mapa,
# tablas de agregación). run_llm=True añade la narrativa LLM por capítulo.
r = render_automatic_eda(
    "/ruta/datos.duckdb", "ventas",
    run_models=True, run_series=True, run_llm=False, out_dir="reports",
)
print("status:", r["status"])
print("pdf:   ", r["pdf_path"], "(", r["n_pages"], "págs )")
print("pptx:  ", r["pptx_path"], "(", r["n_slides"], "slides )")
print("manifest:", r["manifest_path"])
PYEOF

Si además quieres el report Markdown + JSON sidecar y/o el PDF legacy junto al AutomaticEDA, usa profile_table(emit_automatic=True, emit_pdf=True, write_report=True): emite todo a la vez (report_md_path, report_json_path, pdf_path legacy, aeda_pdf_path, aeda_pptx_path, aeda_manifest_path).

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 informe AutomaticEDA (render_automatic_eda / emit_automatic=True) emite el MISMO documento por capítulos a PDF (A5 móvil) y PPTX (16:9) con garantía de no-corte (texto envuelto, tablas partidas repitiendo cabecera, figuras escaladas) y negrita real (**texto**). Escribe automatic_eda_manifest.json con la versión de cada capítulo. Los capítulos modelos/series/geoespacial/agregación se pueblan con los datos crudos que build_eda_render_ctx muestrea de la base (no se traen tablas enteras a RAM).
• El PDF legacy (emit_pdf, render_eda_pdf) sigue disponible y es independiente del AutomaticEDA (A5 vertical, 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.