Installation | Syntax | Examples | Feedback | Change log
(10 Jun 2024)
This package provides the ability to draw treemaps Stata.
It is based on D3's treemap and Python's squarify algorithms.
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.
The SSC version (v1.54):
ssc install treemap, replace
Or it can be installed from GitHub (v1.55):
net install treemap, from("https://raw.githubusercontent.com/asjadnaqvi/stata-treemap/main/installation/") replace
The palettes
package is required to run this command:
ssc install palettes, replace
ssc install colrspace, replace
Even if you have the package installed, make sure that it is updated 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
You can also push the scheme directly into the graph using the scheme(schemename)
option. See the help file for details or the example below.
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:
treemap numvar [if] [in], by(variables (min=1 max=3))
[ xsize(num) ysize(num) percent format(str) sformat(str) labcond(num) palette(it:str) colorby(var)
pad(list) labsize(list) linewidth(list) linecolor(list) fi(list)
addtitles novalues nolabels labsize(num) titlegap(num) labgap(str)
threshold(num) fade(num) labprop titleprop labscale(num) colorprop wrap(num) * ]
See the help file help treemap
for details.
The most basic use is as follows:
treemap numvar, by(variable(s))
where numvar
is a numeric variable, and by()
is upto three string variables, ordered by higher aggregated levels to finer units. The algorithm changes the layout based on xsize()
and ysize()
. See examples below.
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{treemap,
author = {Naqvi, Asjad},
title = {Stata package ``treemap''},
url = {https://github.com/asjadnaqvi/stata-treemap},
version = {1.55},
date = {2024-06-10}
}
or simple text
Naqvi, A. (2024). Stata package "treemap" version 1.55. Release date 10 June 2024. https://github.com/asjadnaqvi/stata-treemap.
or see SSC citation (updated once a new version is submitted)
Set up the data:
clear
set scheme white_tableau
graph set window fontface "Arial Narrow"
use "https://github.com/asjadnaqvi/stata-treemap/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
treemap y_TOT, by(NUTS0) labsize(2.5) title("Population of European countries")
treemap y_TOT, by(NUTS0) labsize(2.5) title("Population of European countries") noval
treemap y_TOT, by(NUTS0) labsize(2) title("Population of European countries") noval xsize(4) ysize(4)
treemap y_TOT, by(NUTS0) labsize(4) title("Population of European countries") noval xsize(5) ysize(2)
treemap y_TOT, by(NUTS0) labsize(5) title("Population of European countries") noval xsize(6) ysize(1)
treemap y_TOT, by(NUTS0 NUTS1) labsize(2) format(%15.0fc)
treemap y_TOT if NUTS0=="AT", by(NUTS2 NUTS3 ) addtitles noval labsize(2) ///
format(%15.0fc) title("Population of Austria at NUTS2 and NUTS3 level")
treemap y_TOT if NUTS0=="NL", by(NUTS2 NUTS3 ) addtitles labsize(2) ///
format(%15.0fc) title("Population of Netherlands at NUTS2 and NUTS3 level")
treemap y_TOT if NUTS0=="NL", by(NUTS2 NUTS3 ) addtitles labsize(1.3) format(%15.0fc) ///
title("Population of Netherlands at NUTS2 and NUTS3 level") palette(CET L07, reverse) xsize(3) ysize(3)
treemap y_TOT if NUTS0=="NL", by(NUTS2 NUTS3 ) addtitles noval labsize(1.3) ///
format(%15.0fc) title("Population of Netherlands at NUTS2 and NUTS3 level") palette(CET L10) xsize(3) ysize(3)
treemap y_TOT if NUTS0=="NL", by(NUTS1 NUTS2 NUTS3 ) addtitles noval labsize(1.3) ///
format(%15.0fc) title("Population of Netherlands at NUTS1-NUTS3 level") palette(CET L10) xsize(3) ysize(3)
treemap y_TOT if NUTS0=="NO", by(NUTS2 NUTS3 ) addtitles labsize(2) format(%15.0fc) ///
title("Population of Norway at NUTS2 and NUTS3 level") palette(CET L20) xsize(3) ysize(3)
treemap y_TOT if NUTS0=="NO", by(NUTS3) addtitles labsize(2) format(%15.0fc) ///
title("Population of Norway at NUTS3 level") palette(CET L19) xsize(5) ysize(3) scheme(neon)
treemap y_TOT, by(NUTS0 NUTS1) addtitles format(%15.0fc) title("Population of European countries")
treemap y_TOT, by(NUTS0 NUTS1) addtitles format(%15.0fc) title("Population of European countries") ///
labprop linew(0.02 0.1) linec(red blue)
treemap y_TOT, by(NUTS0 NUTS1) addtitles format(%15.0fc) title("Population of European countries") ///
labprop linew(none 0.1) linec(red black) labs(2)
treemap y_TOT, by(NUTS0 NUTS1) addtitles labsize(1.6 2.5) format(%15.0fc) title("Population of European countries") ///
labprop colorprop titleprop pad(0.008)
treemap y_TOT, by(NUTS0 NUTS1 NUTS2) format(%15.0fc) title("Population of European countries") nolab
treemap y_TOT, by(NUTS0 NUTS1 NUTS2) format(%15.0fc) title("Population of European countries") nolab pad(0.015 0.015 0.01)
treemap y_TOT, by(NUTS0) labsize(2.5) format(%15.0fc) title("Population of European countries") labprop labcond(5000000)
treemap y_TOT, by(NUTS0 NUTS1 ) labsize(2.2) format(%15.0fc) title("Population of European countries") ///
labprop colorprop titleprop labcond(2000000) addtitles
treemap y_TOT, by(NUTS0 NUTS2 ) labsize(2.2) format(%15.0fc) title("Population of European countries") ///
labprop colorprop titleprop labcond(2000000) addtitles
treemap y_TOT, by(NUTS0 NUTS1 NUTS2 ) linew(none 0.1 none) linec(white black white) labsize(1.4 1.8 2.4) ///
format(%15.0fc) title("Population of European countries") pad(0.015 0.015 0.01) labprop titleprop palette(CET C6) addtitle noval
treemap y_TOT, by(NUTS0 NUTS1 NUTS2 ) linew(none 0.1 none) linec(white black white) labsize(1.0 1.2 1.8) ///
format(%15.0fc) title("Population of European countries") pad(0.015 0.015 0.01) titlegap(0.09) ///
labprop colorprop titleprop labcond(2000000) addtitles xsize(5) ysize(4)
treemap y_TOT if NUTS0=="DE", by(NUTS1 NUTS2 NUTS3 ) linew(none 0.1 none) linec(white black white) labsize(1.4 1.8 2.4) ///
format(%15.0fc) title("Population of Germany") pad(0.015 0.015 0.01) labprop titleprop palette(CET C6) addtitle noval fi(100 50 20)
treemap y_TOT if NUTS0=="DK", by(NUTS2 NUTS3 ) addtitles labsize(2) ///
title("Population of Denmark at NUTS2 and NUTS3 level") subtitle("% of total") percent
treemap y_TOT if NUTS0=="DK", by(NUTS2 NUTS3 ) addtitles labsize(2) title("Population of Denmark at NUTS2 and NUTS3 level") ///
subtitle("% of total") percent format(%3.1f) palette(CET C7) labgap(1)
treemap y_TOT if NUTS0=="ES", by(NUTS1 NUTS3 ) addtitles labsize(2) title("Population of Spain at NUTS1 and NUTS3 level")
treemap y_TOT if NUTS0=="ES", by(NUTS1 NUTS3 ) addtitles labsize(2) title("Population of Spain at NUTS1 and NUTS3 level") ///
threshold(200000) labprop colorprop
treemap y_TOT if NUTS0=="ES", by(NUTS1 NUTS3 ) addtitles labsize(2) title("Population of Spain at NUTS1 and NUTS3 level") ///
threshold(200000) labprop colorprop fade(40)
treemap y_TOT if NUTS0=="IT", by(NUTS1 NUTS2) addtitles labsize(2) labprop
treemap y_TOT if NUTS0=="IT", by(NUTS1 NUTS2) addtitles labsize(2) share labprop
treemap y_TOT if NUTS0=="IT", by(NUTS1 NUTS2) addtitles labsize(2) share labprop format(%10.0f) sformat(%5.2f)
treemap y_TOT if NUTS0=="IT", by(NUTS1 NUTS2) addtitles labsize(2) share labprop noval
treemap y_TOT if NUTS0=="IT", by(NUTS1 NUTS2) addtitles labsize(2) share labprop noval labcond(5)
treemap y_TOT if NUTS0=="IT", by(NUTS1 NUTS2) addtitles labsize(2) noval
Please open an issue to report errors, feature enhancements, and/or other requests.
v1.55 (10 Jun 2024)
- Added
wrap()
for label wrapping. - Minor fixes.
v1.54 (20 Apr 2024)
colorby()
fixed. This option now requires a variable name that determines the color order (reported by Adam Okulicz-Kozaryn).- Minor fixes.
v1.53 (10 Apr 2024)
- Fixed a critical bug where adding three layers was causing errors in the drawing of the second and third layers (reported by Aurelio Tobias).
- Some minor code cleanups.
v1.52 (10 Jan 2024) (unreleased internal version subsumed in v1.53)
- If
by()
variables had empty rows, the program was giving an error. These are now dropped by default.
v1.51 (24 Oct 2023)
- Further stabilized the sort. Categories with same totals were ending up in a random order (reported by Cesar Lopez). This has been fixed.
- Minor code cleanups.
v1.5 (22 Jul 2023)
- Added ability to plot both values and shares.
sformat()
option added to format shares.saving()
option added.labcond()
defaults to percentage shares if bothnoval
andshare
are specified.- Minor bug fixes.
v1.41 (15 Feb 2023)
- Fixed the "Rest of ..." bug.
v1.4 (22 Jan 2023)
- IMPORTANT: The order now need to be specified from highest tier to lowest tier. This reversal in categories is (a) just logical, and (b) aligns
treemap
with other hierarchy packages. - IMPORTANT: the
percent
(from v1.3) has been renamed toshare
(v1.4). This is to aligntreemap
with other hierarchy packages. - Updated defaults in
labgap()
to improve the spacing. - Fixed a bug where the children were not respecting the boundary of the parents.
- Added a
threshold()
option to collapse values below the defined threshold as one category. The collapsed category is renamed to "Rest of ". If only one layer is specified, this category is renamed to "Other" colorprop
now fades to 10% of category color. Previously this was a light shade of grey and didn't look as nice.- A new
fade(val)
option added to change the fade value. - Fixed issue with numeric variables with labels not properly showing up in the labels.
- Added the
colorby(name)
option to allow users to define colors by category names rather than the order defined by relative values. This option might be useful if comparing the same categories over time, especially if their ranking is changing.
v1.3 (14 Dec 2022)
- Fixed issue with the defaults in value formatting.
- Add
percent
option that shows percentage share of the total value rather than actual values. - Added a
labgap()
option that allows the distance of the labels and the values in boxes to be adjusted.
v1.21 (22 Nov 2022)
- Removed error where duplicate values were causing categories to be dropped.
- Stablized the sort order to prevent random trees across different runs.
- Better variable precision and code cleanup.
v1.2 (25 Sep 2022)
- Fill intensity control added.
- Error checks for negative values.
- Minor code cleanups.
v1.1 (13 Sep 2022)
- Major update to the package
- Scaling options added for labels, titles, and colors
- Better checking for thresholds in how boxes are drawn
- Several bug fixes and clean ups to the code.
v1.0 (08 Sep 2022)
- First release.