Lollipop chart
A lollipop chart draws each value as a stem topped with a dot. It carries the same information as a bar chart while being visually lighter — the empty space between the stems makes neighbouring heights easier to compare.
SELECT kuva_render(to_json({
'title': 'Expression by gene',
'x_axis': {'name': 'rank', 'tick_format': 'integer'},
'y_axis': {'name': 'expression'},
'series': [{
'type': 'lollipop',
'points': (SELECT list({'x': gene, 'y': expression} ORDER BY expression DESC)
FROM read_csv_auto('{{DFK_BASE_URL}}data/lollipop.tsv')),
'color': 'steelblue'
}]
})) AS chart;
The gene names go in as they are: x takes a string, the stem is placed at that point's position in the
list, and the name becomes the point's label.
Categorical x
x accepts a string as well as a number. A string means "this observation belongs to that category": the
point is placed at its position in the list (0, 1, 2, …) and the string becomes the point's label —
which is why the example above can pass gene names straight through instead of ranking the rows first. An
explicit label on a point wins over its category name.
This mirrors what kuva's own CLI does when the x column holds strings: the axis stays numeric and the category rides along as the point's label. The position comes from the list order, not from the name, so two points may share a category name and still be drawn apart.
Labels and per-point colours
A point takes an optional label and its own color — that is how you single out the few items worth
naming.
WITH d AS (
SELECT gene, expression,
row_number() OVER (ORDER BY expression DESC) AS pos
FROM read_csv_auto('{{DFK_BASE_URL}}data/lollipop.tsv')
)
SELECT kuva_render(to_json({
'title': 'Top-ranked genes',
'x_axis': {'name': 'rank', 'tick_format': 'integer'},
'y_axis': {'name': 'expression'},
'series': [{
'type': 'lollipop',
'points': (SELECT list(CASE WHEN pos <= 5
THEN {'x': pos, 'y': expression, 'label': gene, 'color': '#d62728'}
ELSE {'x': pos, 'y': expression} END ORDER BY pos) FROM d),
'dot_radius': 5.5
}]
})) AS chart;
Both arms of that CASE produce a struct, and DuckDB unifies their types — which is why the labelled
branch has to spell out the same keys. If the shapes get awkward, build the list in two steps or fall back
to a small inline VALUES table.
Domain annotations
domains draws coloured bands behind the stems, anchored below the baseline. This is the standard
presentation for a mutation landscape, where functional domains are annotated along the sequence.
WITH d AS (
SELECT * FROM (VALUES
( 12.0, 3.0, 'R12H'),
( 35.0, 8.0, 'G35V'),
( 67.0, 2.0, 'K67R'),
( 94.0, 5.0, 'P94L'),
(118.0, 11.0, 'R118*'),
(145.0, 4.0, 'T145A'),
(173.0, 7.0, 'D173N'),
(201.0, 3.0, 'E201K')
) AS t(pos, cnt, mut)
)
SELECT kuva_render(to_json({
'title': 'Mutation landscape',
'x_axis': {'name': 'amino acid position', 'tick_format': 'integer'},
'y_axis': {'name': 'count'},
'series': [{
'type': 'lollipop',
'points': (SELECT list({'x': pos, 'y': cnt, 'label': mut} ORDER BY pos) FROM d),
'domains': [
{'start': 1, 'end': 55, 'label': 'N-term', 'color': '#4e79a7'},
{'start': 56, 'end': 130, 'label': 'Kinase', 'color': '#f28e2b'},
{'start': 131, 'end': 195, 'label': 'SH2', 'color': '#59a14f'},
{'start': 196, 'end': 240, 'label': 'C-term', 'color': '#b07aa1'}
],
'domain_height': 0.8,
'stem_width': 1.5,
'dot_radius': 5
}]
})) AS chart;
domain_height is in data units, measured down from the baseline — so it scales with the y axis, and a
taller chart stretches the bands with it.
Baseline and negative values
Stems originate at baseline (default 0). Values below it grow downward, with their labels placed under
the dot — which is exactly what a log-fold-change chart wants:
SELECT kuva_render(to_json({
'title': 'Log2 fold change',
'x_axis': {'name': 'gene index', 'tick_format': 'integer'},
'y_axis': {'name': 'log2 FC'},
'series': [{
'type': 'lollipop',
'points': [
{'x': 1, 'y': 2.3}, {'x': 2, 'y': -1.8}, {'x': 3, 'y': 0.5},
{'x': 4, 'y': -3.1}, {'x': 5, 'y': 1.9}, {'x': 6, 'y': -0.7},
{'x': 7, 'y': 4.2}
],
'color': 'steelblue',
'baseline': 0,
'baseline_dash': '4 3'
}]
})) AS chart;
show_baseline, baseline_color and baseline_width control the baseline rule itself; dot_stroke and
dot_stroke_width outline the dots.
Fields
| Field | Type | What it sets |
|---|---|---|
points | point[] | Required. One entry per stem: {x, y, label?, color?}; x is a number or a category name. |
domains | domain[] | Background bands: {start, end, label?, color, opacity?}. |
baseline | number | Where the stems originate (default 0). |
stem_width | number | Stem line width (default 1.5). |
dot_radius | number | Dot radius (default 5). |
dot_stroke / dot_stroke_width | string / number | Dot outline colour and width. |
show_baseline | boolean | Draw the horizontal baseline rule (default on). |
baseline_color / baseline_width | string / number | Its colour and width. |
baseline_dash | string | Its dash pattern (e.g. "4 3"). |
domain_height | number | Band height in data units below the baseline (default 0.5). |
color and legend come from series & shared fields. A point's own color
overrides the series colour; tooltips is accepted but not implemented for lollipop.
Notes
pointsmust not be empty.xis a number or a string: a string is a category, the point goes at its position in the list and the string becomes its label. Rank the rows yourself only when the order you want is not the list order.domain_heightis in data units, not pixels, so domains scale with the y axis.- A point below the baseline has its stem drawn downward and its label placed below the dot.
See also
- kuva — Lollipop chart — the plotting library's own reference for this chart.
- Bar chart — the classic filled version.
- Slope — before/after comparisons.
- Pareto — ranked bars with a cumulative line.