help sunburstsunburst v1.6 (GitHub)

sunburst

: A Stata package for sunburst plots.

The command is based on the following guide on Medium: Half-sunburst plots.

Syntax

sunburst numvar [if] [in], by(variables)
[ radius(numlist) step(num) palette(str) colorby(option) colorvar(var) colorprop fade(num) share
format(str) threshold(num) labcondition(num) labcolor(str) lwidth(numlist)
labsize(numlist) lablayer(numlist) labprop labscale(num) points(num)
full cfill(str) clcolor(str) clwidth(str)
title(str) subtitle(str) note(str) scheme(str) name(str) saving(str) aspect(num)
]

sunburst numvar, by(variables) The command requires a numerical variable numvar, plotted over a sequence of heirarchical variables defined by by().
The option by() should be specified from higher grouping category to finer categories. If there are imperfect overlaps in the by() layers, then lower tier layers
will be split based on higher tier layers. Currently, there is no limit to the number of layers that can be specified. But more complex combinations of
layers will result in longer processing times for the graph.

radius(numlist) The radii for the arcs can be manually specified here for fine tuning. Note that the number of radii should be one more than
the number of over() variables. If no option is specified, then the command will automatically start with a radius of 5, incremented in steps of 5.

step(num) The step size for auto-generated radii can be modified here. The default is step(5).

palette(name) Color name is any named scheme defined in the colorpalette package. Default is tableau.
The first layer defined as the first option in by() will determine the colors. The next set of layers will take on this color with slightly lower fill intensities.

colorby(option) Currently only colorby(name) can be specified. This colors the slices based on the alphabetical order of the first layer rather than the order
determined by the value rank in the counter-clockwise direction.

colorvar(var) This option allows assigning custom colors from a variable. The variable should have a unique integer number assigned to the highest by() category variable.
The integers indicate the color number from the palette used. For example if a group has a color variable equal to 4, then the fouth color in the palette will be used. This option is highly useful to ensure
color consistency across different sunburst plots that have overlapping categories regardless of the order they appears in the figures.
Multiple groups can be assigned the same color. If the color variable is missing values, it will be assigned one number higher than the highest value in the group.

colorprop The last layer has a gradient fill across the categories, where the base color is faded from 100% to 10% through equal intervals interpolation.
The fade value can be controlled by the fade() option described below.

fade(num) The amount of fade when using the colorby(layer) option (see above). The default value is fade(10) or 10% of base color.

share Show shares (0-100) rather than values in layer labels. Shares add up to 100 for each by() layer.

threshold(value) The cut-off value below which the values are collapsed into one group, and labeled as "Rest of ...". This option is highly useful if
there are a lot of very small barely-discernible slices. Default is thresh(0).

labcondition(num) The condition for showing value labels. For example, if we only want to display categories with a greater than a value of 100, we can specify
labcond(100). If the share is used, then please specify the share threshold (out of 100). Default is labcond(0).

labcolor(str) The color of the labels. Default is labc(white).

labsize(numlist) The list defining the size of the labels for each layer. Default is labs(2). If only one option is specified, it will apply to all layers.

lablayer(numlist) The list of layers for which to show value labels. For example, if we have three layers and we want label the last two, the syntax is labl(2 3).
Note that first layer is always indexed as layer 1 internally. Default is show value labels for all layers.

labprop Show labels proportional to their size.

labscale(num) Changing the scaling of the proportional labels. Default is labscale(1). A value of <1 penalizes reduces the scaling of smaller values to make them
more visible. This is an advanced option so use it carefully and test with small increments.

format(str) Format the displayed values. Default for standard values is format(%9.0fc) and for shares it is format(%5.2f).

lwidth(numlist) The option can be used to specify a list of line widths for the by() layers. The number of elements should equal the number of variables in by().
Default line widths are 0.12 for the 1...n-1 layers, and 0.02 for the nth layer.

cfill(str) The color fill of the semi circle. Default is cfill(white). This option is especially useful if a non-white background is used.

clcolor(str) Line color of the center circle line. Default is clc(white).

clwidth(str) Line with of the center circle line. Default is clw(0.2).

points(num) Number of points to evaluate an arc. Default value is points(100). If the arc are very small, it is recommended to reduce the points to lower
the memory burden of drawing more points. This is an advanced option so use carefully.

xsize(), ysize(), aspect() For the semi-circle graph, the dimensions have been fixed at xsize(2) and ysize(1).
This naturally results in an aspect ratio of aspect(0.5).
Regardless, these parameters have been made available to allow the users to play around with the dimensions. But use these cautiously.

title(), subtitle(), note() These are standard twoway graph options.

name(), saving() These are standard twoway graph options.

Dependencies

The palette package (Jann 2018, 2022) is required for sunburst:

ssc install palettes, replace
ssc install colrspace, replace

Even if you have these installed, it is highly recommended to update the dependencies:
ado update, update

Examples

See GitHub for examples.

Package details

Version : sunburst v1.6
This release : 26 Jan 2024
First release: 24 Dec 2022
Repository : GitHub
Keywords : Stata, graph, sunburst
License : MIT

Author : Asjad Naqvi
E-mail : asjadnaqvi@gmail.com
Twitter : @AsjadNaqvi

Feedback

Please submit bugs, errors, feature requests on GitHub by opening a new issue.

References

Jann, B. (2018). Color palettes for Stata graphics. The Stata Journal 18(4): 765-785.

Jann, B. (2022). Color palettes for Stata graphics: an update. University of Bern Social Sciences Working Papers No. 43.

Other visualization packages

arcplot, alluvial, bimap, bumparea, bumpline, circlebar, circlepack, clipgeo, delaunay, joyplot,
marimekko, sankey, schemepack, spider, streamplot, sunburst, treecluster, treemap