dashboard-expert

# Dashboard Expert Analyze, build, modify, and explain Mixpanel dashboards. Four modes — pick the one matching the user's intent. ## Mode Selection | User intent | Mode | Key actions | |---|---|---| | "analyze/understand/read/explore dashboard" | **Analyze** | Read structure, execute reports, summarize | | "build/create/make a new dashboard" | **Build** | Investigate data → plan → create with layout | | "modify/update/add to/fix/improve dashboard" | **Modify** | Read current state → plan changes → execute | | "explain/annotate/add insights to dashboard" | **Explain** | Analyze → generate data-driven text cards | ## Quick Start: Analyze an Existing Dashboard ```python import json, re import mixpanel_headless as mp ws = mp.Workspace() dash = ws.get_dashboard(DASHBOARD_ID) layout, contents = dash.layout, dash.contents # Extract structure: rows → cells → content items for row_id in layout["order"]: row = layout["rows"][row_id] for cell in row["cells"]: cid, ctype = str(cell["content_id"]), cell["content_type"] if ctype in ("report", "report-link"): info = contents["report"][cid] print(f" [{cell['width']}w] {info['name']} ({info['type']}) {'[linked]' if ctype == 'report-link' else ''}") elif ctype == "text": md = contents["text"][cid].get("markdown", "") is_header = bool(re.search(r'<h2[\s>]', md, re.I)) print(f" [{cell['width']}w] TEXT {'[SECTION]' if is_header else ''}: {md[:60]}...") # Execute each report → DataFrame for cid, info in contents.get("report", {}).items(): btype, bid = info["type"], info["id"] if btype == "flows": result = ws.query_saved_flows(bid) else: result = ws.query_saved_report(bid, bookmark_type=btype) df = result.df print(f"{info['name']}: {len(df)} rows, columns={list(df.columns)}") ``` ## Quick Start: Build a New Dashboard ```python from mixpanel_headless.types import CreateDashboardParams, DashboardRow, DashboardRowContent import json ws = mp.Workspace() dau = ws.query("Login", math="dau", last=90) def text(html): return DashboardRowContent(content_type="text", content_params={"markdown": html}) def report(name, btype, result): return DashboardRowContent(content_type="report", content_params={ "bookmark": {"name": name, "type": btype, "params": json.dumps(result.params)}}) dashboard = ws.create_dashboard(CreateDashboardParams( title="Product Health", description="Core metrics.", rows=[ DashboardRow(contents=[text("<h2>Product Health</h2><p>Core metrics.</p>")]), DashboardRow(contents=[report("DAU (90d)", "insights", dau)]), ], )) ws.pin_dashboard(dashboard.id) # Make visible to team ``` --- ## Mode: Analyze Read existing dashboards, execute their reports, and synthesize understanding. ### Phase A1: Read Dashboard Structure ```python dash = ws.get_dashboard(dashboard_id) layout, contents = dash.layout, dash.contents ``` Parse the response into a structured representation: - **`layout["order"]`** — ordered list of row IDs - **`layout["rows"][row_id]["cells"]`** — cells with `content_id`, `content_type`, `width` - **`contents["report"][str(content_id)]`** — report metadata: `id` (bookmark_id), `name`, `type`, `params`, `description` - **`contents["text"][str(content_id)]`** — text card: `markdown` **Classify each cell:** - `content_type == "report"` → owned, editable - `content_type == "report-link"` → linked from another dashboard, read-only - `content_type == "text"` → text card; detect section headers via `re.search(r'<h2[\s>]', md, re.I)` **Build a mental model:** Group reports by section (text cards with `<h2>` tags delimit sections). Note each report's chart type, width, and position. ### Phase A2: Extract Report Details For deeper understanding, fetch full bookmark params: ```python bookmark = ws.get_bookmark(bookmark_id) params = bookmark.params # Full query definition dict ``` Key fields in params (Insights format): - `params["sections"]["show"]` — metrics with event names and math type - `params["sections"]["group"]` — breakdown properties - `params["sections"]["filter"]` — active filters - `params["sections"]["time"]` — date range - `params["displayOptions"]["chartType"]` — visualization type Note: `params` in `contents["report"][id]` may be a JSON string — parse with `json.loads()` if needed. ### Phase A3: Execute and Summarize Execute each report to get live data: ```python for cid, info in contents.get("report", {}).items(): bid, btype = info["id"], info["type"] if btype == "flows": result = ws.query_saved_flows(bid) else: result = ws.query_saved_report(bid, bookmark_type=btype) df = result.df ``` **Summarize by report type:** | Type | Key metrics to extract | |---|---| | insights | Total, average, latest value, min, max, trend direction | | funnels | Step names, counts, per-step and overall conversion rate | | retention | Day 1, Day 7, Day 30 rates; stabilization point | | flows | Top paths, conversion rate, drop-off points | **Cross-correlate across reports:** Look for relationships — DAU trends vs. retention, funnel drop-off vs. feature adoption. ### Phase A4: Present Analysis Structure findings as: 1. **Dashboard overview** — title, purpose, section count, report count 2. **Section-by-section breakdown** — what each section measures, key findings 3. **Cross-metric insights** — correlations, anomalies, patterns 4. **Suggestions** — missing metrics, better chart types, layout improvements ### Multi-Dashboard Analysis When analyzing multiple dashboards, build a unified picture: ```python dashboard_ids = [1001, 1002, 1003] all_data = {} for did in dashboard_ids: dash = ws.get_dashboard(did) for cid, info in dash.contents.get("report", {}).items(): result = ws.query_saved_report(info["id"], bookmark_type=info["type"]) all_data[f"{dash.title}/{info['name']}"] = result.df # Cross-dashboard: join DataFrames on date index, compute correlations ``` --- ## Mode: Build Create new dashboards from scratch. Five phases. ### Phase B1: Investigate Before building, discover the data. Never build reports for events with zero volume. ```python ws = mp.Workspace() top = ws.top_events(limit=15) for t in top: print(f"{t.event}: {t.count:,} ({t.percent_change:+.1%})") # Validate candidate events for event in candidate_events: result = ws.query(event, from_date="2025-01-01", to_date="2025-03-31") print(f"{event}: {result.df['count'].sum():,.0f} total") # Explore properties for breakdowns props = ws.properties(event="key_event") values = ws.property_values(event="key_event", property="platform", limit=20) ``` ### Phase B2: Plan Structure Present a proposed structure before building. Choose a template from `references/dashboard-templates.md`. **A plan includes:** title + description, sections with text card headers, reports per section with chart type, grid layout. **Text cards use HTML** (not markdown). Every dashboard must have an intro text card and section headers. **Allowed HTML tags:** `<h1>`, `<h2>`, `<h3>`, `<p>`, `<strong>`, `<em>`, `<u>`, `<s>`, `<mark>`, `<code>`, `<blockquote>`, `<hr>`, `<br>`, `<ul>`, `<ol>`, `<li>`, `<a href="...">` **Forbidden (stripped):** `<div>`, `<span>`, `<b>` (use `<strong>`), `<i>` (use `<em>`), `<img>`, `<table>` **Critical:** Strip `\n` and collapse whitespace from HTML before sending. Each element renders as its own line. **Text card patterns:** ``` Intro: <h2>Dashboard Title</h2><p>What and why. Time period: last 90 days.</p> Section: <h2>Acquisition</h2><p>How users discover and sign up.</p> Explainer: <p>^ Signup conversion is <strong>23.4%</strong>, up 2.1pp.</p> ``` ### Phase B3: Query and Build Query each metric, verify data, then create with layout in one call. ```python def text(html): return DashboardRowContent(content_type="text", content_params={"markdown": html}) def report(name, btype, result, description=None): params = {"bookmark": {"name": name, "type": btype, "params": json.dumps(result.params)}} if description: params["bookmark"]["description"] = description return DashboardRowContent(content_type="report", content_params=params) dashboard = ws.create_dashboard(CreateDashboardParams( title="Product Health Dashboard", description="Key metrics for product health monitoring.", rows=[ DashboardRow(contents=[text("<h2>Product Health</h2><p>Updated daily.</p>")]), DashboardRow(contents=[ report("DAU (90d)", "insights", dau), report("Signups (90d)", "insights", signups), report("Revenue (90d)", "insights", revenue), ]), DashboardRow(contents=[text("<h2>Conversion</h2><p>Key funnels.</p>")]), DashboardRow(contents=[report("Signup Funnel", "funnels", funnel)]), ], )) ``` **On report failure**, substitute a fallback text card: ```python try: result = ws.query(event, math="total", last=90) row_items.append(report(f"{event} Trend", "insights", result)) except Exception as e: row_items.append(text(f"<p><strong>Failed:</strong> {event} — {e}</p>")) ``` ### Phase B4: Enhance - **Pin for team visibility:** `ws.pin_dashboard(dashboard.id)` — dashboards are invisible by default - **Favorite for personal use:** `ws.favorite_dashboard(dashboard.id)` - **Add explainer cards:** see Mode: Explain - **Adjust heights:** see `references/dashboard-reference.md` Section 3.4 ### Phase B5: Verify Open the dashboard and confirm all reports render with data, text cards display correctly, and layout matches the plan. --- ## Mode: Modify Update existing dashboards. Read first, then apply changes in the correct order. ### Phase M1: Read Current State Use Analyze Phase A1-A2 to understand the dashboard's structure. Present to user before making changes. ### Phase M2: Plan Changes Classify each change and plan execution order. Operations **must** follow this sequence: 1. **Metadata** (title/description) — standalone PATCH 2. **Cell creates** — add new content first 3. **Row reorder** (`rows_order`) — after creates so temp IDs resolve 4. **Cell updates** — modify existing content