| name | chart-advisor |
| description | Recommend chart types and generate demo visuals from user-provided numeric lists, CSV/TSV/Markdown-like tables, JSON arrays, spreadsheet extracts, or natural-language data descriptions. Use when the user asks what graph, plot, visualization, figure, dashboard chart, or demo chart best fits their data and analytical purpose, including comparisons, trends, distributions, rankings, relationships, parts-to-whole, outliers, before/after changes, or presentation-ready chart suggestions. |
Chart Advisor
Core Workflow
- Identify the user's analytical purpose before choosing a chart. Infer it from the prompt when possible; ask one concise question only when the goal changes the chart choice materially.
- Profile the data: number of rows, number of series, variable types, likely time/order columns, category cardinality, missing values, negative values, outliers, and whether values are absolute, rates, shares, or ranks.
- Recommend 1-3 chart options. Put the best default first, explain the tradeoff, and name any chart types to avoid.
- Generate at least one demo chart when data is available. Prefer a quick, inspectable SVG/PNG over a polished final figure unless the user asks for production styling.
- Return the recommendation, short rationale, data caveats, and paths to generated chart files.
Chart Selection
Use references/chart-selection.md when the choice is not obvious, when the data has multiple possible stories, or when explaining tradeoffs.
Default mapping:
- Trend over ordered time/index: line chart. Use small multiples for many series.
- Category comparison or ranking: sorted horizontal bar chart. Use vertical bars only for short labels and few categories.
- Distribution of one numeric variable: histogram. Add box/violin only if the target tool supports it.
- Relationship between two numeric variables: scatter plot. Add size/color encodings only when they carry a clearly separate variable.
- Part-to-whole at one point: stacked bar or 100% stacked bar. Use pie/donut only for 2-5 slices and a simple share story.
- Before/after or paired change: slope chart or connected dot plot.
- Deviation from target/baseline: diverging bar chart or indexed line.
- Matrix or dense two-way comparison: heatmap.
Avoid 3D charts, dual axes unless there is a strong reason, rainbow palettes, unsorted category bars, pie charts with many slices, and line charts for unordered categories.
Demo Generation
Use scripts/chart_demo.py for deterministic demo output without external dependencies. It accepts inline values, CSV/TSV files, and JSON arrays, then creates SVG charts plus a Markdown recommendation report.
Examples:
python scripts/chart_demo.py --data "12, 18, 16, 25, 31, 29" --goal "show monthly trend" --out-dir demo
python scripts/chart_demo.py --input sales.csv --goal "compare revenue by region" --out-dir demo --charts auto
python scripts/chart_demo.py --input data.json --goal "show relationship between price and conversion" --out-dir demo --charts scatter,line
When the user provides table text directly in chat, save it to a temporary .csv or pass a simple numeric list through --data. If richer visual styling, annotations, non-SVG formats, or advanced statistical charts are needed, create a bespoke chart using the local plotting stack available in the workspace, while keeping this script as the fallback.
Response Shape
Keep the answer practical:
- Lead with the recommended chart type and why it fits the user's purpose.
- Mention the backup option when another chart would emphasize a different story.
- Include design guidance: sorting, axis choice, labels, color, aggregation, and whether to normalize.
- Link generated demo files with local paths.
- State limitations if the source data is too sparse, ambiguous, heavily aggregated, or likely needs cleaning.
Do not over-explain general visualization theory. Focus on what this specific dataset and purpose need.
