analytics

Compétence Analytics

Analyse de science des données flexible qui fonctionne avec n'importe quel ensemble de données. Découverte automatique du schéma, recommandation de visualisations et export au format create-figure.

Démarrage rapide (Tout ensemble de données)

cd .pi/skills/analytics

# Étape 1 : Découvrir ce que contiennent les données
./run.sh describe data.jsonl

# Étape 2 : Voir les recommandations et générer un graphique
./run.sh chart data.jsonl --name distribution_channel -o chart.json

# Étape 3 : Rendre avec create-figure
cd .agent/skills/create-figure
./run.sh metrics -i /path/to/chart.json --type bar -o chart.pdf

Le Pipeline Transparent

Toutes données (JSONL/JSON/CSV)
         │
         ▼
┌─────────────────────────────────┐
│     analytics describe          │  ← Découvre le schéma, recommande des graphiques
│  "5 colonnes catégorie, 2       │
│   numériques, 1 temporelle"     │
│  Recommandations :              │
│   - distribution_channel (bar)  │
│   - trend_by_date (line)        │
│   - heatmap_hour_x_day          │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│     analytics chart/group-by    │  ← Génère les données du graphique au format create-figure
│  --name distribution_channel    │
│  -o chart.json                  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│     create-figure metrics       │  ← Produit des PDF/PNG de qualité publication
│  -i chart.json --type bar       │
│  -o channel_distribution.pdf    │
└─────────────────────────────────┘

Commandes

Découverte (Commencez ici)

Commande	Description
describe <file>	Découvrir le schéma, détecter les types de colonnes, recommander des graphiques

./run.sh describe sales.jsonl
# Résultat :
# Colonnes : date (temporelle), product (catégorie), amount (numérique), region (catégorie)
# Recommandations :
#   1. distribution_product - Distribution de product
#   2. distribution_region - Distribution de region
#   3. trend_by_date - Comptage par date
#   4. heatmap_product_x_region - product vs region

Analyse Flexible

Commande	Description
group-by <file>	Grouper par n'importe quelle colonne avec agrégation
stats <file>	Statistiques numériques et corrélations
chart <file>	Générer une spécification de graphique pour create-figure

# Grouper par n'importe quelle colonne
./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

# Statistiques numériques
./run.sh stats data.jsonl --columns revenue,cost,profit

# Générer un graphique à partir d'une recommandation
./run.sh chart data.jsonl --name distribution_channel -o chart.json

Données Horodatées (sorties ingest-*)

Commande	Description
insights <file>	Résumé d'analyse complet (tendances, sessions, motifs)
trends <file>	Tendances de visualisation avec moyennes mobiles
sessions <file>	Détection de sessions et analyse de binge
time-patterns <file>	Distribution horaire/journalière
evolution <file>	Comment les préférences changent au fil du temps

Sortie

Commande	Description
export <file>	Exportation groupée de tous les graphiques standard
report <file>	Rapport narratif de style Horus

Formats Pris en Charge

Format	Extension	Détection automatique
JSONL	.jsonl	JSON délimité par ligne
JSON	.json	Tableau ou {data: [...]}
CSV	.csv	Valeurs séparées par des virgules

Détection des Types de Colonnes

La commande describe détecte automatiquement :

Type	Logique de détection	Graphiques recommandés
temporel	datetime64, chaînes de type date	line, area, heatmap (axe temporel)
numérique	int64, float64	histogram, scatter, stats
catégoriel	faible cardinalité (≤20 uniques)	bar, pie, heatmap
booléen	dtype bool	pie (vrai/faux)
texte	chaînes de haute cardinalité	nuage de mots, top-N

Recommandations de Graphiques

Basées sur les types de colonnes, analytics recommande :

Motif de données	Type de graphique	Commande create-figure
1 catégoriel	bar, pie	metrics --type bar
1 temporel	line	training-curves
2 catégoriels	heatmap	heatmap
temporel + catégoriel	heatmap	heatmap
2+ numériques	matrice de corrélation	heatmap
1 numérique	histogram	metrics --type bar

Flux de Travail pour Agent

Pour qu'un agent projet analyse n'importe quel ensemble de données et le visualise :

# 1. Découvrir le schéma
result = run("./run.sh describe data.jsonl --json")
recommendations = result["recommendations"]

# 2. Choisir la première recommandation
chart_name = recommendations[0]["name"]
cmd = recommendations[0]["create_figure_cmd"]

# 3. Générer les données du graphique
run(f"./run.sh chart data.jsonl --name {chart_name} -o chart.json")

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

Exemples

Données de Vente E-commerce

# Données : orders.jsonl avec date, product, category, amount, region

./run.sh describe orders.jsonl
# → Recommande : 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

Historique YouTube (ingest-yt-history)

# Utiliser des commandes spécialisées pour données horodatées
./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

Données de Réponse API

# Données : api_logs.json avec 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

Dépendances

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

Intégration avec Horus

# Style narratif Horus
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl --horus

# Résultat :
# "Vos habitudes de visionnage révèlent une tendance nocturne vers un contenu mélancolique.
#  L'activité maximale se produit pendant les heures crépusculaires, avec une consommation musicale
#  qui s'intensifie lors des sessions nocturnes introspectives..."

Erreurs Courantes

# FAUX : Appeler stats directement sur un ensemble de données inconnu
./run.sh stats data.jsonl --columns revenue,cost
# → Échoue sur les colonnes non numériques ("USD 1000" est du texte, pas un nombre)
# JUSTE : Toujours exécuter describe d'abord
./run.sh describe data.jsonl
# → Affiche les types de colonnes, recommande les commandes de graphiques correctes

# FAUX : Choisir manuellement le type de graphique sans la recommandation de describe
./run.sh group-by data.jsonl --by date --agg views | ./run.sh metrics --type pie
# → Un graphique circulaire pour des données temporelles est inutile
# JUSTE : Utiliser la commande create-figure recommandée par describe

# FAUX : Supposer que le schéma JSONL correspond aux attentes
# → Champs renommés, valeurs NULL présentes, types mélangés
# JUSTE : describe détecte automatiquement tout cela