https://github.com/asjadnaqvi/stata-sunburst
A Stata package for sunburst plots
https://github.com/asjadnaqvi/stata-sunburst
ado dataviz graph package stata sunburst
Last synced: 3 months ago
JSON representation
A Stata package for sunburst plots
- Host: GitHub
- URL: https://github.com/asjadnaqvi/stata-sunburst
- Owner: asjadnaqvi
- License: mit
- Created: 2022-12-20T14:00:17.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-21T12:01:50.000Z (8 months ago)
- Last Synced: 2025-03-10T06:34:46.636Z (3 months ago)
- Topics: ado, dataviz, graph, package, stata, sunburst
- Language: Stata
- Homepage:
- Size: 42.6 MB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
     
---
[Installation](#Installation) | [Syntax](#Syntax) | [Citation guidelines](#Citation-guidelines) | [Examples](#Examples) | [Feedback](#Feedback) | [Change log](#Change-log)
---
# sunburst v1.8
(16 Oct 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.8**):
```
ssc install sunburst, replace
```
GitHub (**v1.8**):
```
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) wrap(num)
full rotate(angle) 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)
```
## 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. Suggested citations:
*in BibTeX*
```
@software{sunburst,
author = {Naqvi, Asjad},
title = {Stata package ``sunburst''},
url = {https://github.com/asjadnaqvi/stata-sunburst},
version = {1.8},
date = {2024-10-16}
}
```
*or simple text*
```
Naqvi, A. (2024). Stata package "sunburst" version 1.8. Release date 16 October 2024. https://github.com/asjadnaqvi/stata-sunburst.
```
*or see [SSC citation](https://ideas.repec.org/c/boc/bocode/s459164.html) (updated once a new version is submitted)*
## 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.8: circle fill + rotate
```
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)
```
```
sunburst pop if NUTS0=="PT", by(NUTS2 NUTS3) full clc(black) lc(black) rotate(90)
```
## Feedback
Please open an [issue](https://github.com/asjadnaqvi/stata-sunburst/issues) to report errors, feature enhancements, and/or other requests.
## Change log
**v1.8 (16 Oct 2024)**
- Options `wrap()` and `cfill()` now depend on [graphfunctions](https://github.com/asjadnaqvi/stata-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](https://github.com/asjadnaqvi/stata-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.