Installation | Syntax | Citation guidelines | Examples | Feedback | Change log
(27 June 2024)
This package provides the ability to draw waffles Stata. It is based on the Waffle plots guide on Medium.
The package is still beta and is being constantly improved. It might still be missing checks and features.
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.2):
ssc install waffle, replace
Or it can be installed from GitHub (v1.21):
net install waffle, from("https://raw.githubusercontent.com/asjadnaqvi/stata-waffle/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:
waffle numvar(s) [if] [in],
[ by(variable) over(variable) normvar(variable) percent showpct format(fmt) palette(name)
rowdots(num) coldots(num) aspect(num) msymbol(list) msize(list) mlwidth(list)
ndsymbol(str) ndsize(str) ndcolor(str) cols(num) margin(str) legcolumns(num) legposition(pos) legsize(str)
note(str) subtitle(str) *
]
See the help file help waffle
for details.
The basic use for wide form is:
waffle variables
and for long form is:
waffle variable, by()
where variable(s)
are a set of numeric 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{waffle,
author = {Naqvi, Asjad AND Colston, Jared},
title = {Stata package ``waffle''},
url = {https://github.com/asjadnaqvi/stata-waffle},
version = {1.21},
date = {2024-07-21}
}
or simple text
Naqvi, A. & Colston, J. (2024). Stata package "waffle" version 1.21. Release date 21 June 2024. https://github.com/asjadnaqvi/stata-waffle.
or see SSC citation (updated once a new version is submitted)
Set up the data in wide form:
clear
sysuse pop2000, clear
// generate a categorical variable
gen agecat = .
replace agecat = 1 if agegrp <= 3
replace agecat = 2 if inrange(agegrp, 4, 13)
replace agecat = 3 if agegrp >=14
tab agegrp agecat
lab de agecat 1 "<15" 2 "15-64" 3 "> 65+"
lab val agecat agecat
Let's test the basic command:
waffle white black asian indian
Add additional catgories:
waffle white black asian indian, over(agecat) note("")
waffle white black asian indian, over(agecat) note("") showpct
Above the higher category determines the relatively heights. But we can also adjust it by a normalizaing variable normvar()
which in this case is the total population variable:
waffle white black asian indian, over(agecat) normvar(total) note("")
waffle white black asian indian, over(agecat) normvar(total) note("") showpct
We can also normalize each block local percentages of each category:
waffle white black asian indian, over(agecat) percent note("")
And change the color palettes:
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) note("")
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) ///
note("Graphs by race") xsize(2) ysize(1)
We can also fully customize the marker symbols and marker sizes:
waffle white black asian indian, over(agecat) normvar(total) ///
palette(okabe) msym(triangle circle square) msize(1.5 1.6) ///
note("") xsize(2) ysize(1)
This also works well if there is a single color, e.g. for black and white graphs:
waffle white black asian indian, over(agecat) normvar(total) ///
palette(black) msym(Oh triangle +) msize(1.8 1.5 2.4) ///
note("") xsize(3) ysize(1)
waffle white black asian indian, over(agecat) normvar(total) ///
palette(black) msym(Oh triangle +) msize(1.8 1.5 2.4) ///
note("") xsize(3) ysize(1)
waffle white black asian indian, over(agecat) normvar(total) ///
palette(black) msym(Oh triangle +) msize(1.8 1.5 2.4) mlwid(0.5 0.2 0.5) ///
note("") xsize(3) ysize(1) ///
legsize(3) subtitle(, size(4) pos(6) nobox) ndsym(circle) ndcolor(red) ndsize(0.1)
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) rowdots(10) note("")
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) rowdots(10) msize(2.2) note("")
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) rowdots(5) msize(3) note("")
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) rowdots(5) msize(3) ///
note("") margin(large)
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) rowdots(10) msize(1.1) ///
note("") cols(2) xsize(1) ysize(1)
waffle white black asian indian, over(agecat) normvar(total) palette(okabe) rowdots(10) msize(1.1) ///
note("") cols(2) xsize(1) ysize(1)
Convert the data to long form:
sysuse pop2000, clear
keep white black asian indian island agegrp total
gen id = _n
ren white y_white
ren black y_black
ren asian y_asian
ren indian y_indian
ren island y_island
reshape long y_ , i(id agegrp total) j(byvar) string
sort byvar agegrp
gen agecat = .
replace agecat = 1 if agegrp <= 3
replace agecat = 2 if inrange(agegrp, 4, 13)
replace agecat = 3 if agegrp >=14
tab agegrp agecat
lab de agecat 1 "<15" 2 "15-64" 3 "> 65+"
lab val agecat agecat
gen groups = .
replace groups = 1 if byvar=="indian"
replace groups = 2 if byvar=="asian"
replace groups = 3 if byvar=="black"
replace groups = 4 if byvar=="white"
replace groups = 5 if byvar=="island"
lab de groups 1 "Indian" 2 "Asian" 3 "Blacks" 4 "White" 5 "Island", replace
lab val groups groups
drop if groups==5
bysort byvar: egen normvar = sum(total)
format normvar %18.0fc
and run the command with long options:
waffle y_ , by(groups) over(agecat) normvar(normvar) note("") showpct
Please open an issue to report errors, feature enhancements, and/or other requests.
v1.21 (27 May 2024)
- Fixed a bug where the program was running into an error if
by()
was not specified. - Fixed and improved returned locals. See
return list
after running the command. - The program now displays the value of each dot after the graph is drawn.
v1.2 (26 May 2024)
- Program has been converted into r-class where
r(dot)
returns the value of each box. Seereturn list
after running the command. - Fixed a major bug with long data format that was not displaying the totals correctly.
- Better treatment of null values. Previous version was still drawing zero categories.
v1.11 (05 May 2024)
- Several bug fixes in how data was being collapsed in both long and wide form.
- For long form, the option
normvar()
should now by already calculated. For wide form, each row ofnormvar()
is assumed to be different and summed up. These options might still evolve to better fit use cases.
v1.1 (04 Apr 2024)
- Rerelease with reworked code. This version is still beta.
- Allows long and wide data forms.
- More flexibility with colors, markers, sizes, placements.
v1.0 (01 Mar 2022)
- First release