Installation | Syntax | Citation guidelines | Examples | Feedback | Change log
(10 Jun 2024)
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.71):
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"
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) wrap()
full cfill(str) clcolor(str) clwidth(str) *
]
See the help file help sunburst
for details.
The most basic use is as follows:
sunburst value, by(variables)
Software packages take countless hours of programming, testing, and bug fixing. If you use this package, then a citation would be highly appreciated. Suggested citations:
in BibTeX
@software{sunburst,
author = {Naqvi, Asjad},
title = {Stata package ``sunburst''},
url = {https://github.com/asjadnaqvi/stata-sunburst},
version = {1.71},
date = {2024-06-10}
}
or simple text
Naqvi, A. (2024). Stata package "sunburst" version 1.71. Release date 10 June 2024. https://github.com/asjadnaqvi/stata-sunburst.
or see SSC citation (updated once a new version is submitted)
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)
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.")
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)
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)
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)
sunburst pop if NUTS0=="ES", by(NUTS2 NUTS3) labprop
sunburst pop if NUTS0=="ES", by(NUTS2 NUTS3) labprop labscale(0.6)
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)
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)
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
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)
Please open an issue to report errors, feature enhancements, and/or other requests.
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()
andclwidth()
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 thelabprop
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 optioncolorby(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.