grahama1970/analytics

Skill de Analítica

Analítica de ciencia de datos flexible que funciona con cualquier conjunto de datos. Auto-descubre esquemas, recomienda visualizaciones y exporta en formato create-figure.

Inicio Rápido (Cualquier Dataset)

cd .pi/skills/analytics

# Paso 1: Descubrir qué hay en los datos
./run.sh describe data.jsonl

# Paso 2: Ver recomendaciones y generar gráfico
./run.sh chart data.jsonl --name distribution_channel -o chart.json

# Paso 3: Renderizar con create-figure
cd .agent/skills/create-figure
./run.sh metrics -i /path/to/chart.json --type bar -o chart.pdf

El Pipeline sin Fricción

Cualquier Dato (JSONL/JSON/CSV)
         │
         ▼
┌─────────────────────────────────┐
│   analytics describe            │  ← Descubre esquema, recomienda gráficos
│  "5 columnas categóricas, 2     │
│   numéricas, 1 temporal detectadas"│
│  Recomendaciones:               │
│   - distribution_channel (bar)  │
│   - trend_by_date (line)        │
│   - heatmap_hour_x_day          │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│   analytics chart/group-by      │  ← Genera datos de gráfico en formato create-figure
│  --name distribution_channel    │
│  -o chart.json                  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│   create-figure metrics         │  ← Renderiza PDF/PNG de calidad publicitaria
│  -i chart.json --type bar       │
│  -o channel_distribution.pdf    │
└─────────────────────────────────┘

Comandos

Descubrimiento (Empezar Aquí)

Comando	Descripción
describe <archivo>	Descubre esquema, detecta tipos de columna, recomienda gráficos

./run.sh describe sales.jsonl
# Salida:
# Columnas: date (temporal), product (categórica), amount (numérica), region (categórica)
# Recomendaciones:
#   1. distribution_product - Distribución de product
#   2. distribution_region - Distribución de region
#   3. trend_by_date - Conteo over date
#   4. heatmap_product_x_region - product vs region

Análisis Flexible

Comando	Descripción
group-by <archivo>	Agrupa por cualquier columna con agregación
stats <archivo>	Estadísticas numéricas y correlaciones
chart <archivo>	Genera especificación de gráfico para create-figure

# Agrupar por cualquier columna
./run.sh group-by data.jsonl --by channel --for-figure -o by_channel.json
./run.sh group-by data.jsonl --by category --agg price --func sum

# Estadísticas numéricas
./run.sh stats data.jsonl --columns revenue,cost,profit

# Generar gráfico desde recomendación
./run.sh chart data.jsonl --name distribution_channel -o chart.json

Datos con Marca Temporal (salidas ingest-*)

Comando	Descripción
insights <archivo>	Resumen completo de análisis (tendencias, sesiones, patrones)
trends <archivo>	Tendencias de visualización con medias móviles
sessions <archivo>	Detección de sesiones y análisis de atracones
time-patterns <archivo>	Distribución por hora/día
evolution <archivo>	Cómo cambian las preferencias con el tiempo

Salida

Comando	Descripción
export <archivo>	Exporta en lote todos los gráficos estándar
report <archivo>	Reporte narrativo estilo Horus

Formatos Soportados

Formato	Extensión	Auto-Detección
JSONL	.jsonl	JSON delimitado por líneas
JSON	.json	Array o {data: [...]}
CSV	.csv	Separado por comas

Detección de Tipos de Columna

El comando describe auto-detecta:

Tipo	Lógica de Detección	Gráficos Recomendados
temporal	datetime64, strings con aspecto de fecha	línea, área, heatmap (eje temporal)
numérica	int64, float64	histograma, dispersión, stats
categórica	baja cardinalidad (≤20 únicos)	barra, pastel, heatmap
booleana	dtype bool	pastel (verdadero/falso)
texto	strings de alta cardinalidad	nube de palabras, top-N

Recomendaciones de Gráficos

Basado en los tipos de columna, analytics recomienda:

Patrón de Datos	Tipo de Gráfico	Comando create-figure
1 categórica	barra, pastel	metrics --type bar
1 temporal	línea	training-curves
2 categóricas	heatmap	heatmap
temporal + categórica	heatmap	heatmap
2+ numéricas	matriz de correlación	heatmap
1 numérica	histograma	metrics --type bar

Flujo de Trabajo del Agente

Para que un agente de proyecto analice cualquier dataset y visualice:

# 1. Descubrir esquema
result = run("./run.sh describe data.jsonl --json")
recommendations = result["recommendations"]

# 2. Elegir primera recomendación
chart_name = recommendations[0]["name"]
cmd = recommendations[0]["create_figure_cmd"]

# 3. Generar datos del gráfico
run(f"./run.sh chart data.jsonl --name {chart_name} -o chart.json")

# 4. Renderizar
run(f"cd .agent/skills/create-figure && ./run.sh {cmd} -i chart.json -o chart.pdf")

Ejemplos

Datos de Ventas de E-commerce

# Datos: orders.jsonl con date, product, category, amount, region

./run.sh describe orders.jsonl
# → Recomienda: distribution_category, distribution_region, trend_by_date

./run.sh group-by orders.jsonl --by category --agg amount --func sum --for-figure -o revenue_by_category.json
# → {"metrics": {"Electronics": 45000, "Clothing": 32000, ...}}

cd .agent/skills/create-figure
./run.sh metrics -i revenue_by_category.json --type bar -o revenue.pdf

Historial de YouTube (ingest-yt-history)

# Usar comandos especializados con marca temporal
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl
./run.sh export ~/.pi/ingest-yt-history/history.jsonl -o ./charts --for-figure

cd .agent/skills/create-figure
./run.sh heatmap -i charts/heatmap.json -o viewing_heatmap.pdf

Datos de Respuesta de API

# Datos: api_logs.json con endpoint, status_code, response_time, user_id

./run.sh describe api_logs.json
./run.sh stats api_logs.json --columns response_time
# → mean=245.3ms, std=89.2ms, p50=220ms, p99=450ms

./run.sh group-by api_logs.json --by endpoint --agg response_time --func mean --for-figure -o latency.json

Dependencias

# pyproject.toml
dependencies = [
    "pandas>=2.0.0",
    "typer>=0.9.0",
    "rich>=13.0.0",
]

Integración con Horus

# Estilo narrativo Horus
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl --horus

# Salida:
# "Tus patrones de visualización revelan una tendencia nocturna hacia contenido melancólico.
#  La actividad máxima ocurre en las horas del crepúsculo, con el consumo de música intensificándose
#  durante sesiones introspectivas nocturnas..."

Errores Comunes

# MAL: Llamar a stats directamente sobre un dataset desconocido
./run.sh stats data.jsonl --columns revenue,cost
# → Fallo en columnas no numéricas ("USD 1000" es texto, no número)
# BIEN: Siempre ejecutar describe primero
./run.sh describe data.jsonl
# → Muestra tipos de columna, recomienda comandos de gráfico correctos

# MAL: Elegir tipo de gráfico manualmente sin recomendación de describe
./run.sh group-by data.jsonl --by date --agg views | ./run.sh metrics --type pie
# → Gráfico de pastel para datos de serie temporal es inútil
# BIEN: Usar el comando create-figure recomendado por describe

# MAL: Asumir que el esquema JSONL cumple las expectativas
# → Campos renombrados, nulos presentes, tipos mezclados
# BIEN: describe detecta todo esto automáticamente