Installation | Syntax | Examples | Feedback | Change log

(19 Oct 2023)

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

ssc install alluvial, replace

GitHub (v1.21):

net install alluvial, from("https://raw.githubusercontent.com/asjadnaqvi/stata-alluvial/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  

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:

alluvial varlist [if] [in] [weight], 
                [ 
                  palette(str) colorby(layer|level) smooth(1-8) gap(num) recenter(mid|bot|top) 
                  labangle(str) labsize(str) labposition(str) labgap(str) showtotal
                  valsize(str) valcondition(num) valformat(str) valgap(str) novalues
                  lwidth(str) lcolor(str) alpha(num) offset(num) boxwidth(str)
                  title(str) subtitle(str) note(str) scheme(str) name(str) xsize(num) ysize(num) 
                ]

See the help file help alluvial for details.

The most basic use is as follows:

alluvial varlist

where varlist are categorival variables given at the unit of observation. If any variable has more than 10 categories, or it is continuous, the command will throw an error. This is to avoid over-crowding the figure. For suggestions on how to automate this, please open an issue!

Load the Stata dataset

sysuse nlsw88.dta, clear

Let's test the alluvial command:

alluvial race married collgrad smsa union

alluvial race married collgrad smsa union, smooth(1)

alluvial race married collgrad smsa union, smooth(8)

alluvial race married collgrad smsa union, colorby(layer)

alluvial race married collgrad smsa union, palette(carto)

alluvial race married collgrad smsa union, palette(CET I2)

alluvial race married collgrad smsa union, shares

alluvial race married collgrad smsa union, showmiss shares

alluvial race married collgrad smsa union, gap(0)

alluvial race married collgrad smsa union, gap(10)

local vars race married collgrad smsa union

alluvial `vars',  smooth(8) alpha(60) palette(CET C7) gap(10) valcond(100) valsize(2) showtot ///
	xsize(2) ysize(1) lc(black) lw(0.1) 

local vars race married collgrad smsa union
alluvial `vars',  smooth(8) alpha(60) palette(CET C7) gap(10) valcond(100) valsize(2) showtot ///
	xsize(2) ysize(1) lc(black) lw(0.1) ///
	laba(0) labpos(3) noval offset(6)

local vars race married collgrad smsa union
alluvial `vars',  smooth(8) alpha(60) palette(CET C7) gap(10) valcond(100) valsize(2) showtot ///
	xsize(2) ysize(1) lc(black) lw(0.1) ///
	laba(0) labpos(3) noval offset(6) boxwid(6)

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

v1.21 (19 Oct 2023)

• showmiss was not generating the missing values category (reported by Matthias Schonlau). This has been fixed.

v1.2 (04 Apr 2023)

• if/in added back in the command.
• boxwidth() added to the command.
• Minor bug fixes.

v1.1 (15 Jan 2023)

• Variable labels are now correctly passing to the final graph (requested by Marc Kaulisch and Ana Karen Díaz Méndez).
• Weights option added. Still in beta so more testing is required (requested by Ana Karen Díaz Méndez).
• offset option added to extend the x-axis (requested by Marc Kaulisch).
• valcond is now just a numeric. It is assumed that the condition implies >= <valcond>.
• The missing category, enabled using the showmiss option, now has its own color (requested by Marc Kaulisch).

v1.0 (08 Dec 2022)

• Public release.