---

Installation | Syntax | Examples | Feedback | Change log

---

sunburst v1.7

(07 Feb 2024)

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.7):

ssc install sunburst, replace

GitHub (v1.7):

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

The palettes package is required to run this command:

ssc install palettes, replace
ssc install colrspace, 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:

ssc install schemepack, replace
set scheme white_tableau  

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

graph set window fontface "Arial Narrow"

Syntax

The syntax for the latest version is as follows:

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) 
                ]

See the help file help sunburst for details.

The most basic use is as follows:

sunburst value, by(variables)

Examples

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

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

drop year
keep NUTS_ID y_TOT

drop if y_TOT==0

keep if length(NUTS_ID)==5

gen NUTS2 = substr(NUTS_ID, 1, 4)
gen NUTS1 = substr(NUTS_ID, 1, 3)
gen NUTS0 = substr(NUTS_ID, 1, 2)
ren NUTS_ID 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

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

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

v1.6 center circle fill options

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

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

Feedback

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

Change log

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.