qwen_agent/skills/common/data-dashboard/hooks/dashboard_guide.md

## Data Visualization Tools Usage Guide

Three tools are available for rendering data visualizations:
- `render_metrics` — Metric card dashboard (KPIs, stats)
- `render_chart` — Single chart (line, bar, pie, radar, scatter, gauge)
- `render_multi_chart` — Multiple charts in a grid layout

---

### 1. render_metrics

When to use: KPIs, stats, numerical summaries, side-by-side comparisons.

```
render_metrics(
  title="Sales Overview",
  metrics=[
    {"label": "Revenue", "value": "$12,345", "change": "+12.5%", "change_type": "up"},
    {"label": "Users", "value": "1,234", "change": "-3.2%", "change_type": "down"},
    {"label": "Conversion", "value": "4.5%", "change_type": "neutral"}
  ]
)
```

---

### 2. render_chart

When to use: trends, comparisons, distributions, compositions, single metric gauges.

#### Line chart — trends over time
```
render_chart(
  title="Monthly Revenue",
  chart_type="line",
  data={
    "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
    "series": [
      {"name": "2024", "data": [820, 932, 901, 934, 1290, 1330]},
      {"name": "2025", "data": [620, 732, 801, 1034, 1190, 1530]}
    ]
  },
  smooth=true
)
```

#### Bar chart — comparisons
```
render_chart(
  title="Sales by Region",
  chart_type="bar",
  data={
    "categories": ["North", "South", "East", "West"],
    "series": [
      {"name": "Q1", "data": [320, 302, 341, 374]},
      {"name": "Q2", "data": [220, 182, 191, 234]}
    ]
  },
  stacked=true,
  show_label=true
)
```

#### Pie chart — proportions
```
render_chart(
  title="Traffic Sources",
  chart_type="pie",
  data={
    "series": [{
      "name": "Sources",
      "data": [
        {"name": "Search", "value": 1048},
        {"name": "Direct", "value": 735},
        {"name": "Email", "value": 580},
        {"name": "Social", "value": 484}
      ]
    }]
  }
)
```

#### Radar chart — multi-dimensional
```
render_chart(
  title="Skill Assessment",
  chart_type="radar",
  data={
    "categories": ["Sales", "Admin", "Tech", "Support", "Marketing"],
    "series": [
      {"name": "Alice", "data": [4200, 3000, 20000, 35000, 50000]},
      {"name": "Bob",   "data": [5000, 14000, 28000, 26000, 42000]}
    ]
  }
)
```

#### Scatter chart — correlation
```
render_chart(
  title="Height vs Weight",
  chart_type="scatter",
  data={
    "series": [
      {"name": "Male",   "data": [[161, 51], [167, 59], [159, 49], [175, 73]]},
      {"name": "Female", "data": [[150, 45], [160, 55], [165, 60], [155, 50]]}
    ]
  }
)
```

#### Gauge chart — single KPI
```
render_chart(
  title="CPU Usage",
  chart_type="gauge",
  data={"series": [{"name": "CPU", "data": [72.5]}]}
)
```

#### Chart options:
- `width`: CSS width, default "100%"
- `height`: CSS height, default "400px"
- `theme`: "light" (default) or "dark"
- `stacked`: stack series (line/bar), default false
- `smooth`: smooth curves (line), default false
- `show_label`: show data labels, default false

---

### 3. render_multi_chart

When to use: comprehensive overviews, multiple related charts, business reports.

```
render_multi_chart(
  title="Monthly Business Report",
  columns=2,
  theme="light",
  charts=[
    {
      "title": "Revenue Trend",
      "chart_type": "line",
      "data": {
        "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
        "series": [{"name": "Revenue", "data": [820, 932, 901, 934, 1290, 1330]}]
      },
      "smooth": true
    },
    {
      "title": "Sales by Region",
      "chart_type": "bar",
      "data": {
        "categories": ["North", "South", "East", "West"],
        "series": [
          {"name": "Q1", "data": [320, 302, 341, 374]},
          {"name": "Q2", "data": [220, 182, 191, 234]}
        ]
      }
    },
    {
      "title": "Traffic Sources",
      "chart_type": "pie",
      "data": {
        "series": [{"name": "Sources", "data": [
          {"name": "Search", "value": 1048},
          {"name": "Direct", "value": 735},
          {"name": "Social", "value": 484}
        ]}]
      }
    },
    {
      "title": "Server Load",
      "chart_type": "gauge",
      "data": {"series": [{"name": "CPU", "data": [67]}]},
      "height": "300px"
    }
  ]
)
```

### Tips:
- Always choose the most appropriate chart_type for the data
- Use line for time-series trends, bar for category comparisons
- Use pie for proportions (limit ~7 segments), radar for multi-dimensional scores
- Use scatter for correlation, gauge for single KPI (0-100)
- Set height: "400px" for most charts, "300px" for gauge
- Multi-chart: columns=2 for 2-4 charts, keep 4-6 max per call