---

Installation | Syntax | Citation guidelines | Examples | Feedback | Change log

---

sunburst v1.9

(25 Jun 2025)

Installation

The package can be installed via SSC or GitHub. The GitHub version, might be more recent due to bug fixes, feature updates etc, and may contain syntax improvements and changes in default values. See version numbers below. Eventually the GitHub version is published on SSC.

SSC (v1.8):

ssc install sunburst, replace

GitHub (v1.9):

net install sunburst, from("https://raw.githubusercontent.com/asjadnaqvi/stata-sunburst/main/installation/") replace

The palettes package is required to run this command:

stata ssc install palettes, replace ssc install colrspace, replace ssc install graphfunctions, replace

Even if you have these packages installed, please check for updates: ado update, update.

If you want to make a clean figure, then it is advisable to load a clean scheme. These are several available and I personally use the following:

stata ssc install schemepack, replace set scheme white_tableau

I also prefer narrow fonts in figures with long labels. You can change this as follows:

stata graph set window fontface "Arial Narrow"

Syntax

The syntax for the latest version is as follows:

stata 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) rotate(degrees) full cfill(str) clcolor(str) clwidth(str) wrap(num) asis * ]

See the help file help sunburst for details.

The most basic use is as follows:

sunburst value, by(variables)

Citation guidelines

Software packages take countless hours of programming, testing, and bug fixing. If you use this package, then a citation would be highly appreciated.

The SSC citation is recommended. Please note that the GitHub version might be newer than the SSC version.

Examples

Load the Stata dataset which contains the population of European regions:

``` use "https://github.com/asjadnaqvi/stata-sunburst/blob/main/data/demorpjangrp3_clean.dta?raw=true", clear

drop year keep NUTSID yTOT

drop if y_TOT==0

keep if length(NUTS_ID)==5

gen NUTS2 = substr(NUTSID, 1, 4) gen NUTS1 = substr(NUTSID, 1, 3) gen NUTS0 = substr(NUTSID, 1, 2) ren NUTSID NUTS3 ren y_TOT pop format pop %12.0fc ```

Let's test the sunburst command:

sunburst pop, by(NUTS0)

sunburst pop, by(NUTS0) labsize(3) lw(2)

sunburst pop if NUTS0=="FR", by(NUTS1 NUTS2)

sunburst pop if NUTS0=="FR", by(NUTS1 NUTS2) labsize(3 3) lw(0.5 0.25) format(%15.0fc)

sunburst pop if NUTS0=="FR", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%15.0fc)

sunburst pop if NUTS0=="FR", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) threshold(500000) format(%15.0fc)

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) threshold(100000) format(%15.0fc)

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) labcond(1000000) format(%15.0fc)

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) labcond(1000000) format(%15.0fc)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS2 NUTS3) labsize(2.2 1.8 1.4) lw(0.2 0.1 0.01) format(%15.0fc) colorprop

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS2 NUTS3) labsize(2.2 1.8 1.4) lw(0.2 0.1 0.01) format(%15.0fc) colorprop threshold(500000)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS2 NUTS3) labsize(2.2 1.8 1.4) lw(0.2 0.1 0.01) format(%15.0fc) colorprop threshold(500000) palette(CET C6)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS2 NUTS3) labsize(2.2 1.8 1.4) lw(0.2 0.1 0.01) format(%15.0fc) colorprop threshold(500000) palette(CET C6, reverse)

Shares

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%5.1fc) share

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%5.1fc) share threshold(1000000)

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%5.1fc) share labcond(2) threshold(300000) colorprop

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%5.1fc) share labcond(2) threshold(200000) colorprop radius(6 12 24)

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%5.1fc) share labcond(2) /// threshold(200000) colorprop radius(6 12 24) /// title("My (half) sunburst figure in Stata") subtitle("Some more info here") note("Made using the #sunburst package.")

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) labsize(2 2) lw(0.2 0.02) format(%5.1fc) share labcond(2) /// threshold(200000) colorprop radius(6 12 24) /// title("My (half) sunburst figure in Stata") subtitle("Some more info here") note("Made using the #sunburst package.")

fade (v1.1)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS3) labsize(2 2) lw(0.2 0.01) lc(white) format(%5.1fc) /// share labcond(2) colorprop fade(60)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS3) labsize(2 2) lw(0.2 0.01) lc(white) format(%5.1fc) /// share labcond(2) colorprop fade(0)

colorby(name) (v1.2)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS3) labsize(2 2) lw(0.2 0.01) lc(white) format(%5.1fc) /// share labcond(2) colorprop fade(60) colorby(name)

labellayer() (v1.3)

sunburst pop if NUTS0=="ES", by(NUTS1 NUTS2 NUTS3) lablayer(2 3) /// labsize(2.2 1.4 1.4) lw(0.2 0.1 0.01) labcond(100000) format(%15.0fc)

labprop and labscale (v1.4)

sunburst pop if NUTS0=="ES", by(NUTS2 NUTS3) labprop

sunburst pop if NUTS0=="ES", by(NUTS2 NUTS3) labprop labscale(0.6)

colorvar (v1.5)

Let's generate a plot with specific list of countries:

sunburst pop if inlist(NUTS0, "AT", "NO", "DK", "NL"), by(NUTS0 NUTS1) labprop labscale(0.6) format(%12.0fc)

If we want to preserve the color assignment, we generate a custom variable:

gen colors = . replace colors = 1 if NUTS0=="AT" replace colors = 2 if NUTS0=="NO" replace colors = 3 if NUTS0=="NL" replace colors = 4 if NUTS0=="DK" replace colors = 5 if NUTS0=="FI"

and we can pass it on to the command and keep the colors consistent across the layers:

sunburst pop if inlist(NUTS0, "AT", "NO", "DK", "NL"), by(NUTS0 NUTS1) labprop labscale(0.6) format(%12.0fc) colorvar(colors)

sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1) labprop labscale(0.6) format(%12.0fc) colorvar(colors)

sunburst pop if inlist(NUTS0, "NO", "AT", "NL", "FI"), by(NUTS0 NUTS1) labprop labscale(0.6) format(%12.0fc) colorvar(colors)

colorvar(), colorby(), and colorprop tests

Two layers

sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS2) labprop labscale(0.6) format(%12.0fc) colorprop sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS2) labprop labscale(0.6) format(%12.0fc) colorprop colorby(name) sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS2) labprop labscale(0.6) format(%12.0fc) colorprop colorvar(colors)

Three layers

sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1 NUTS3) labprop labscale(0.6) format(%12.0fc) colorprop sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1 NUTS3) labprop labscale(0.6) format(%12.0fc) colorprop colorby(name) sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1 NUTS3) labprop labscale(0.6) format(%12.0fc) colorprop colorvar(colors)

Four layers

sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1 NUTS2 NUTS3) labprop labscale(0.6) format(%12.0fc) colorprop sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1 NUTS2 NUTS3) labprop labscale(0.6) format(%12.0fc) colorprop colorby(name) sunburst pop if inlist(NUTS0, "NO", "DK", "NL", "FI"), by(NUTS0 NUTS1 NUTS2 NUTS3) labprop labscale(0.6) format(%12.0fc) colorprop colorvar(colors)

v1.6 full option

stata sunburst pop if NUTS0=="AT", by(NUTS1 NUTS2 NUTS3) full labs(1.4 1.4 1.4)

stata sunburst pop if NUTS0=="FR", by(NUTS1 NUTS2) full labprop

v1.8: circle fill + rotate

stata sunburst pop if NUTS0=="PT", by(NUTS2 NUTS3) clc(black) lc(black)

stata sunburst pop if NUTS0=="PT", by(NUTS2 NUTS3) full clc(black) lc(black)

stata sunburst pop if NUTS0=="PT", by(NUTS2 NUTS3) full clc(black) lc(black) rotate(90)

v1.9 asis

stata sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) full labprop labsize(1.8 2.5) radius(10 30 40) palette(CET C6)

sunburst pop if NUTS0=="DE", by(NUTS1 NUTS2) full labprop labsize(1.8 2.5) radius(10 30 40) palette(CET C6) asis

Feedback

Please open an issue to report errors, feature enhancements, and/or other requests.

Change log

v1.9 (23 Jun 2025) - Added option asis which preserves the data input order. - Various bug fixes.

v1.8 (16 Oct 2024) - Options wrap() and cfill() now depend on graphfunctions for better figures. - Added option rotate(). This will only work if a full figure is drawn using full (requested by Eric Melse).

v1.71 (07 Feb 2024) - Added wrap() option for label wrapping. - Minor code cleanups.

v1.7 (07 Feb 2024) - Fixed a major bug where repeated categories in second or higher layers were causing misalignment of arcs. - Changes some of the internal variables to tempvars to avoid potential conflicts with common variable names. - Fixed the orientation of the variable labels in the 4th quadrant if the full circle option was used. - Minor cleanups.

v1.6 (26 Jan 2024) - Rewrite of core routines. - Added full option to generate a full circle. - Added clcolor() and clwidth() options to better control central circle fill. - Minor code cleanups.

v1.5 (23 Aug 2023) - Implements the colorvar(var) option to allow full control of assigning the colors (requested by Richard Mills). - Major code cleanups.

v1.4 (05 Aug 2023) - Fixed a major bug that was causing categories with similar values to shuffle in the figure (reported by Richard Mills). - Fixed a bug where empty by() categories were causing the alignment of arcs to mess up. - Added labprop option to make labels proportional. - Added labscale() option to change how the labels scale in the labprop option. - Added saving() option. - Added points() option to allow users to define how much points for each arc need to be calculated. - Several minor code cleanups.

v1.3 (23 Jun 2023) - Fixed a major precision bug that was causing slices to be mis-aligned, and labels to skip. - Added labcolor(), cfill(), lablayer() (requested by Zumin Shi) options. - Various bug fixes.

v1.2 (22 Jan 2023) - Bug in threshold() collapse fixed. - Option colorprop added to simplify specifying the gradient fill. This also aligns it with the treemap package. - Option colorby() simplified to currently accepting one option colorby(name) which assign colors based on the alphabetical order (requested by Marc Kaulisch).

v1.1 (14 Jan 2023) - This version fixes the draw order of layers which is now determined by size rather than names. This makes the layouts more palatable to the eye. - Added several error checks. - The option threshold() will not collapse to "Rest of ..." if there is only one variable. - Colors now fade to 10% of base color. - A fade() option allows users to control the fade level. - Various bug fixes plus code cleanup.

v1.0 (24 Dec 2022) - Public release.