Skip to main content

Sunburst chart

A sunburst chart lays a hierarchy out as concentric rings: the innermost ring is the top level, each further ring a deeper level, and an arc's width within its ring is proportional to that node's value. It uses the same node model as the treemap — only the geometry differs.

WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/sunburst.tsv')),
kids AS (
SELECT parent AS p, list({'label': label, 'value': value} ORDER BY value DESC) AS ch
FROM d WHERE parent IS NOT NULL AND parent <> ''
GROUP BY parent
)
SELECT kuva_render(to_json({
'title': 'Classes',
'series': [{
'type': 'sunburst',
'roots': (SELECT list({'label': r.label,
'children': COALESCE(k.ch, CAST([] AS STRUCT(label VARCHAR, value DOUBLE)[]))}
ORDER BY r.label)
FROM d r
LEFT JOIN kids k ON k.p = r.label
WHERE r.parent IS NULL OR r.parent = ''),
'color_mode': 'by_parent'
}]
})) AS chart;

The rings read outward as the hierarchy deepens, and the angle at any radius is the share of that level. An inner node's own value is summed from its children, so a parent's arc is always as wide as the sum of its parts.

Several roots​

Multiple roots share the innermost ring, each taking a distinct palette colour. It is the shape to use when the top level is a small set of independent categories rather than one root.

SELECT kuva_render(to_json({
'title': 'Two groups',
'series': [{
'type': 'sunburst',
'roots': [
{'label': 'Frontend', 'children': [
{'label': 'React', 'value': 50},
{'label': 'Vue', 'value': 30},
{'label': 'Svelte', 'value': 20}
]},
{'label': 'Backend', 'children': [
{'label': 'Rust', 'value': 40},
{'label': 'Go', 'value': 35},
{'label': 'Python', 'value': 25}
]}
],
'color_mode': 'by_parent'
}]
})) AS chart;

Donut style​

inner_radius is a fraction of the outer radius, clamped to [0, 0.95]. A hole of 0.3–0.35 keeps the centre calm and leaves room for a total or a title, which is what makes a sunburst readable in a dashboard.

WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/sunburst.tsv')),
kids AS (
SELECT parent AS p, list({'label': label, 'value': value} ORDER BY value DESC) AS ch
FROM d WHERE parent IS NOT NULL AND parent <> ''
GROUP BY parent
)
SELECT kuva_render(to_json({
'title': 'Donut style',
'series': [{
'type': 'sunburst',
'roots': (SELECT list({'label': r.label,
'children': COALESCE(k.ch, CAST([] AS STRUCT(label VARCHAR, value DOUBLE)[]))}
ORDER BY r.label)
FROM d r
LEFT JOIN kids k ON k.p = r.label
WHERE r.parent IS NULL OR r.parent = ''),
'inner_radius': 0.35,
'ring_gap': 2
}]
})) AS chart;

Colour modes​

color_modeArcs
"by_parent"Inherit their root's colour (default)
"explicit"Use the node's own color
{"color_map": "viridis"}Coloured by value, with the parent arcs left neutral

In by-value mode the inner arcs are drawn in a neutral grey, because a ring's parent has no single value to colour by — an arc cannot be both its own colour and the sum of its children's.

WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/sunburst.tsv')),
kids AS (
SELECT parent AS p, list({'label': label, 'value': value} ORDER BY value DESC) AS ch
FROM d WHERE parent IS NOT NULL AND parent <> ''
GROUP BY parent
)
SELECT kuva_render(to_json({
'title': 'Coloured by value',
'series': [{
'type': 'sunburst',
'roots': (SELECT list({'label': r.label,
'children': COALESCE(k.ch, CAST([] AS STRUCT(label VARCHAR, value DOUBLE)[]))}
ORDER BY r.label)
FROM d r
LEFT JOIN kids k ON k.p = r.label
WHERE r.parent IS NULL OR r.parent = ''),
'color_mode': {'color_map': 'viridis'},
'colorbar': true,
'colorbar_label': 'value'
}]
})) AS chart;

Second-dimension colouring​

color_values is a flat, depth-first list of numbers parallel to the leaves, so size can encode one quantity and colour another — the GO-enrichment pattern, where the arc is the gene count and the colour is the p-value.

SELECT kuva_render(to_json({
'title': 'Size versus significance',
'series': [{
'type': 'sunburst',
'roots': [
{'label': 'GO:0006955', 'value': 120},
{'label': 'GO:0007049', 'value': 85},
{'label': 'GO:0016310', 'value': 60}
],
'color_values': [-10, -6.7, -4.3],
'color_mode': {'color_map': 'viridis'},
'colorbar': true,
'colorbar_label': '-log10(p)'
}]
})) AS chart;

-log10(p) rather than p itself: the colour scale should run dark-to-bright as significance increases, and there is no sensible colour for a p-value of 0.

Angles, rings and labels​

FieldDefaultWhat it sets
start_angle0Degrees, 0 = twelve o'clock, running clockwise
ring_gap1Gap between rings, in pixels
show_labelstrueDraw the arc labels
min_label_angle15Do not label an arc sweeping less than this
rotate_labelstrueRotate labels along the circumference
max_depth—Depth limit
WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/sunburst.tsv')),
kids AS (
SELECT parent AS p, list({'label': label, 'value': value} ORDER BY value DESC) AS ch
FROM d WHERE parent IS NOT NULL AND parent <> ''
GROUP BY parent
)
SELECT kuva_render(to_json({
'title': 'Rotated start, wider rings',
'series': [{
'type': 'sunburst',
'roots': (SELECT list({'label': r.label,
'children': COALESCE(k.ch, CAST([] AS STRUCT(label VARCHAR, value DOUBLE)[]))}
ORDER BY r.label)
FROM d r
LEFT JOIN kids k ON k.p = r.label
WHERE r.parent IS NULL OR r.parent = ''),
'start_angle': 90,
'ring_gap': 3,
'min_label_angle': 8,
'max_depth': 2
}]
})) AS chart;

Fields​

FieldTypeWhat it sets
rootsnode[]Required. One entry per root; each is {label, value?, color?, children?}.
valuenumberA leaf's size; summed from the children on an inner node.
childrennode[]Nested nodes.
color_modestring | object"by_parent" (default) · "explicit" · {"color_map": …}.
color_valuesnumber[]Flat depth-first values for the colour encoding.
color_range[number, number]Clamp the colour scale.
colorbar / colorbar_labelboolean / stringThe colour bar and its title.
inner_radiusnumberInner hole as a fraction of the outer radius, clamped to [0, 0.95].
ring_gapnumberGap between rings, in pixels.
start_anglenumberThe first arc's angle, in degrees.
show_labels / min_label_angleboolean / numberArc labels and their minimum sweep.
rotate_labelsbooleanRotate labels with the circumference.
max_depthintegerDepth limit.
tooltipsbooleanSVG hover tooltips (default on).

Notes​

  • roots must not be empty. Every node needs a label; a leaf also needs a value.
  • children must be an empty list, never null — hence the COALESCE(…, CAST([] AS …)) in the SQL.
  • inner_radius is a fraction, unlike the pie chart's inner_radius, which is in pixels. The two fields share a name and nothing else.
  • Arcs below min_label_angle are left unlabelled, so a hierarchy with many small leaves ends up relying on the tooltips or a legend.
  • color_values must be in depth-first leaf order and exactly as long as the leaf count.

See also​