grahama1970/analytics

Analytics Skill

Flexible Datenwissenschaftsanalysen, die mit jedem Datensatz funktionieren. Automatische Schemaerkennung, empfiehlt Visualisierungen und exportiert im create-figure-Format.

Kurzanleitung (Jeder Datensatz)

cd .pi/skills/analytics

# Schritt 1: Entdecken, was in den Daten steckt
./run.sh describe data.jsonl

# Schritt 2: Empfehlungen ansehen und Diagramm generieren
./run.sh chart data.jsonl --name distribution_channel -o chart.json

# Schritt 3: Mit create-figure rendern
cd .agent/skills/create-figure
./run.sh metrics -i /path/to/chart.json --type bar -o chart.pdf

Die nahtlose Pipeline

Beliebige Daten (JSONL/JSON/CSV)
         │
         ▼
┌─────────────────────────────────┐
│     analytics describe          │  ← Entdeckt Schema, empfiehlt Diagramme
│  "5 kategoriale, 2 numerische,  │
│   1 zeitliche Spalte erkannt"   │
│  Empfehlungen:                  │
│   - distribution_channel (balken) │
│   - trend_by_date (linie)        │
│   - heatmap_hour_x_day           │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│     analytics chart/group-by    │  ← Generiert Diagrammdaten im create-figure-Format
│  --name distribution_channel    │
│  -o chart.json                  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│     create-figure metrics       │  ← Rendert publikationsreife PDF/PNG
│  -i chart.json --type bar       │
│  -o channel_distribution.pdf    │
└─────────────────────────────────┘

Befehle

Erkundung (Hier beginnen)

Befehl	Beschreibung
describe <datei>	Schema erkennen, Spaltentypen bestimmen, Diagramme empfehlen

./run.sh describe sales.jsonl
# Ausgabe:
# Spalten: date (zeitlich), product (kategorial), amount (numerisch), region (kategorial)
# Empfehlungen:
#   1. distribution_product - Verteilung von product
#   2. distribution_region - Verteilung von region
#   3. trend_by_date - Anzahl über date
#   4. heatmap_product_x_region - product vs region

Flexible Analyse

Befehl	Beschreibung
group-by <datei>	Nach einer beliebigen Spalte mit Aggregation gruppieren
stats <datei>	Numerische Statistiken und Korrelationen
chart <datei>	Diagrammspezifikation für create-figure generieren

# Nach einer beliebigen Spalte gruppieren
./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

# Numerische Statistiken
./run.sh stats data.jsonl --columns revenue,cost,profit

# Diagramm aus einer Empfehlung generieren
./run.sh chart data.jsonl --name distribution_channel -o chart.json

Zeitgestempelte Daten (ingest-*-Ausgaben)

Befehl	Beschreibung
insights <datei>	Vollständige Analysezusammenfassung (Trends, Sitzungen, Muster)
trends <datei>	Betrachtungstrends mit gleitenden Durchschnitten
sessions <datei>	Sitzungserkennung und Bingeverhalten-Analyse
time-patterns <datei>	Stunden-/Tagesverteilung
evolution <datei>	Wie sich Präferenzen im Laufe der Zeit ändern

Ausgabe

Befehl	Beschreibung
export <datei>	Batch-Export aller Standarddiagramme
report <datei>	Horus-artiger narrativer Bericht

Unterstützte Formate

Format	Erweiterung	Automatische Erkennung
JSONL	.jsonl	Zeilenweise JSON
JSON	.json	Array oder {data: [...]}
CSV	.csv	Komma-getrennt

Spaltentyperkennung

Der describe-Befehl erkennt automatisch:

Typ	Erkennungslogik	Empfohlene Diagramme
zeitlich	datetime64, datumsähnliche Zeichenketten	Linie, Fläche, Heatmap (Zeitachse)
numerisch	int64, float64	Histogramm, Punktdiagramm, Statistiken
kategorial	geringe Kardinalität (≤20 eindeutige Werte)	Balken, Kreis, Heatmap
boolesch	bool dtype	Kreis (true/false)
text	hohe Kardinalität Zeichenketten	Wortwolke, Top-N

Diagrammempfehlungen

Basierend auf den Spaltentypen empfiehlt analytics:

Datenmuster	Diagrammtyp	create-figure-Befehl
1 kategorial	Balken, Kreis	metrics --type bar
1 zeitlich	Linie	training-curves
2 kategorial	Heatmap	heatmap
zeitlich + kategorial	Heatmap	heatmap
2+ numerisch	Korrelationsmatrix	heatmap
1 numerisch	Histogramm	metrics --type bar

Agenten-Workflow

Damit ein Projekt-Agent einen beliebigen Datensatz analysieren und visualisieren kann:

# 1. Schema erkennen
result = run("./run.sh describe data.jsonl --json")
empfehlungen = result["recommendations"]

# 2. Erste Empfehlung auswählen
diagramm_name = empfehlungen[0]["name"]
cmd = empfehlungen[0]["create_figure_cmd"]

# 3. Diagrammdaten generieren
run(f"./run.sh chart data.jsonl --name {diagramm_name} -o chart.json")

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

Beispiele

E-Commerce-Verkaufsdaten

# Daten: orders.jsonl mit date, product, category, amount, region

./run.sh describe orders.jsonl
# → Empfiehlt: 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": {"Elektronik": 45000, "Kleidung": 32000, ...}}

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

YouTube-Verlauf (ingest-yt-history)

# Spezialisierte zeitgestempelte Befehle verwenden
./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

API-Antwortdaten

# Daten: api_logs.json mit 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

Abhängigkeiten

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

Integration mit Horus

# Horus-Erzählstil
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl --horus

# Ausgabe:
# "Ihre Betrachtungsmuster zeigen eine nächtliche Neigung zu melancholischen Inhalten.
#  Die Spitzenaktivität tritt in den Dämmerungsstunden auf, wobei der Musikkonsum
#  während introspektiver Nachtsitzungen intensiver wird..."

Häufige Fehler

# FALSCH: Direkt stats auf unbekannten Datensatz anwenden
./run.sh stats data.jsonl --columns revenue,cost
# → Fehlschlag bei nicht-numerischen Spalten ("USD 1000" ist Text, keine Zahl)
# RICHTIG: Zuerst immer describe ausführen
./run.sh describe data.jsonl
# → Zeigt Spaltentypen an, empfiehlt korrekte Diagrammbefehle

# FALSCH: Diagrammtyp ohne describe-Empfehlung manuell wählen
./run.sh group-by data.jsonl --by date --agg views | ./run.sh metrics --type pie
# → Kreisdiagramm für Zeitreihendaten ist nutzlos
# RICHTIG: Die empfohlenen create-figure-Befehle von describe verwenden

# FALSCH: Annahme, dass JSONL-Schema den Erwartungen entspricht
# → Felder umbenannt, Nullwerte vorhanden, Typen gemischt
# RICHTIG: describe erkennt all dies automatisch