chart-choice-by-relationship
Use when deciding whether a number needs a chart at all and, if so, which form: pick by the relationship the reader must see (change over time, ranking, part-to-whole, deviation from target, distribut
SKILL.mdskills/chart-choice-by-relationship/SKILL.md
GitHubChoose the chart by the relationship
Start from the sentence the reader should come away with, name the relationship in it, then pick the form. If the sentence has one number, it probably needs no chart.
Step 0: does it need a chart?
| Situation | Use |
|---|---|
| One or two numbers | a sentence: "Orders: 212 in September, up from 188 in August." |
| Exact values will be looked up | a table (sorted, units in the header) |
| A shape, trend, spread or pattern is the point | a chart |
| A process, dependency or flow | a diagram (nodes and edges), not a chart |
Step 1: name the relationship
| Relationship | Reader's question | First choice | Alternatives | Avoid |
|---|---|---|---|---|
| Change over time | How did it move? | line | column bars for few, discrete periods; slope chart for two points | pie per period, 3D |
| Ranking | Who is biggest? | horizontal bars, sorted | dot plot | unsorted bars, alphabetical order without reason |
| Magnitude comparison | How much bigger? | bars from zero | dot plot (when zero is irrelevant) | bubbles, pictograms with fractional icons |
| Deviation | Above or below target / last year? | diverging bars around the reference | line with reference line | two separate bars the reader must subtract |
| Part-to-whole | What share? | stacked bar (≤ about 4 parts) or sorted bars of shares | pie only for ≤ about 5 parts with one dominant | pie with similar slices or a missing slice; donut |
| Part-to-whole over time | How did the mix change? | stacked area or 100% stacked bars (few parts) | small multiples of lines | many-layer stacked areas (middle layers unreadable) |
| Distribution | How spread, skewed, multi-modal? | histogram; dot/strip plot for small n | ECDF, box plot, quantile dotplot | a bar of the mean alone |
| Correlation | Do two measures move together? | scatter (with n) | heatmap of binned counts for large n | dual-axis line chart |
| Flow / funnel | Where do we lose people? | horizontal bars per stage with counts and step rates | Sankey for branching flows | funnel graphics whose widths are not proportional |
| Spatial | Where? | map only when location matters to the decision | table by region | choropleth of raw counts (map population instead) |
| Uncertainty | How sure? | see uncertainty-display |
Limits above are guidance, not hard rules: the UK Analysis Function suggests about four lines per line chart, four parts per stack, four bars per cluster and five slices per pie; summaries of Wong's guide report the same limit of about four lines (never more than five). Beyond them, use small multiples or highlight one series and grey the rest.
Step 2: map to ieeVisualizer (spec 1.0)
| Form | How |
|---|---|
| Line over time | timeseries template (units, forecast split, caller-supplied bounds) or line mark |
| Bars, ranking, deviation | bar mark, orientation: "horizontal" for rankings and long labels; sort the data upstream |
| Stacked / shares | bar or area with series; compute shares upstream and set the unit to % |
| Distribution | histogram mark (bins or bin_edges, density); scatter of raw points for small n |
| Correlation | scatter mark; heatmap for binned counts |
| Funnel | funnel template (stage counts, step and overall rates with their numerators and denominators), or a horizontal bar mark with stage order preserved |
| Reference / target | reference_line / reference_band annotations, or the template's target |
| Fields, functions | quiver, function, vector_field_2d template |
| Grouped comparison, vs previous period | bar_comparison template |
| Small multiples, dual-panel | not in one FigureSpec: render one figure per panel with identical axis limits, or place them side by side in a ViewSpec grid |
| Flow / architecture diagram | a flow component in a ViewSpec (ieeVisualizer.view, docs/VIEWS.md); do not fake it with a scatter plot |
| Network, hierarchy, dependencies | network, org_chart, dependency_map templates (ieeVisualizer.network, docs/NETWORKS.md) |
If none fits, follow the extensibility ladder in ieevisualizer-figures
(template → compose marks → specialist adapter → bespoke code, rarely).
Good / bad
Bad: pie chart of orders by source with eight similar slices. Good: horizontal bars, sorted, labelled with counts and shares, "Other" last regardless of size.
Bad: line chart joining "North, South, East, West" regions (categories are not a sequence). Good: sorted bars.
Bad: for an ablation with three seeds per variant, bars of the mean
accuracy.
Good: dot plot of the three seed results per variant with the mean marked
(ml-results-reporting).
Checklist
- The one-sentence takeaway is written before the chart is chosen.
- A sentence or table was considered and rejected for a reason.
- The form matches the relationship in the table above.
- Categories without natural order are sorted by value; ordered ones (stages, months, age bands) keep their order.
- Series and part counts are within guidance, or highlighted/split.
- Comparisons across panels use identical scales.
Adapted in part from Anthropic's data-visualization skill (Apache-2.0) and
the UK Analysis Function chart guidance (OGL v3.0); changed: rewritten,
reorganised by reader question, ieeVisualizer mapping added. Sources and
licences: SOURCES.md.