help sankeysankey v1.71 (GitHub)

sankey

: A Stata package for Sankey diagrams.

Syntax

sankey value [if] [in], from(var) to(var) by(var)
[ palette(str) colorby(layer|level) colorvar(var) stock colorvarmiss(str) colorboxmiss(str)
smooth(1-8) gap(num) recenter(mid|bot|top) ctitles(list) ctgap(num) ctsize(num) ctposition(bot|top)
labangle(str) labsize(str) labposition(str) labgap(str) showtotal labprop labscale(num)
valsize(str) valcondition(num) format(str) valgap(str) novalues valprop valscale(num)
novalright novalleft nolabels sort1(value|name[, reverse]) sort2(value|order[, reverse])
lwidth(str) lcolor(str) alpha(num) offset(num) boxwidth(str) percent
title(str) subtitle(str) note(str) scheme(str) name(str) xsize(num) ysize(num) saving(str) ]

Please report errors/bugs/enhancement requests on GitHub.

sankey numvar, from() to() by() The command plots a numeric numvar variable that is defined by source from() and destination to()
across by() levels. Both from() and to() should be string variables. If they are not, then they are converted to strings. This is to ensure that
mapping across by() levels remains consistent. The level by() should be a numeric variable defined in increments of 1.

palette(name) Color name is any named scheme defined in the colorpalette package. Default is tableau.

sort1(name|value[, reverse]) Users can sort the boxes for each layer by using value or name (default).
The sort1(value) organizes the boxes based on their values, while sort1(name) arranges them alphabetically.
Both can be combined with reverse, e.g. sort1(value, reverse) or sortby(name, reverse). Note that you can specify a custom sort by using value labels.

sort2(order|vaue[, reverse]) Users can sort the links between the boxes using value or order (default).
The sort2(value) arranges the links numerically, while sort2(order) arranges them in the order they originate. The latter is also aesthetically more pleasing
since it avoids links unnecessarily crossing each other.

stock This is an advanced option that collapses own flows (source = destination) as stocks. Own flows are no longer shown as links but add to the stocks
that is reflected by the height of the boxes. This option can be useful if own flows are not be be considered as leakages from one layer to another.

colorby(option) Users can color the diagram by layer instead of the default where each unique name is taken as a unique color category.
The layer option is determined by the by() variable, and it will give each layer a unique color. Alternatively, use the colorvar() option below.

colorvar(var) Users can color the diagram by variable. The variable should contain integer values starting from 1. Any categories that are not assigned
a color will be automatically grayed out. The color of these categories can be controlled using the option below. Note that either colorvar() or colorby()
can be specified.

colorvarmiss(str) Define the colors of the flows of the missing categories not defined in colorvar(). Default is colorvarmiss(gs12).

colorboxmiss(str) Define the colors of the boxes of the missing categories not defined in colorvar(). Default is colorboxmiss(gs10).

smooth(num) This option allows users to smooth out the spider plots connections. It can take on values between 1 to 8, where 1 is for straight lines, while
is 8 shows steps. The middle range between 3-6 gives more curvy links. The default value is smooth(4).

gap(num) Gap between categories is defined as a percentage of the highest y-axis range across the layers. Default value is gap(2) for 2%.

recenter(option) Users can recenter the graph middle (mid or m also accepted), top (or t), or bottom (or bot or b).
This is mostly an aesthetic choice. Default value is recen(mid).

alpha(num) The transparency control of the area fills. The value ranges from 0-100, where 0 is no fill and 100 is fully filled.
Default value is alpha(75) for 75% transparency.

lwidth(str) The outline width of the area fills. Default is lw(none). This implies that they are turned off by default.

lcolor(str) The outline color of the area fills. Default is lc(white).

percent Beta option: Covert flow values into percentage share of category bars. Might give messy output if outflows are greater than inflows.
Use cautiously.

Bars

labsize(str) The size of the bar labels. Default is labs(2).

labprop Scale the bar labels based on the relative stocks.

labscale(num) Scale factor of labprop. Default value is labscale(0.3333). Advance option, use carefully.

labangle(str) The angle of the bar labels. Default is laba(90) for vertical labels.

labcolor(str) The color of the bar labels. Default is labc(black).

nolabels Hide the bar labels.

labposition(str) The position of the bar labels. Default is labpos(0) for centered.

labgap(str) The gap of the bars from the mid point. Default is labg(0) for no gap.
If the label angle is change to horitzontal or the label position is changed from 0, then labg() can be used to fine-tune the placement.

showtotal Display the category totals on the bars.

boxwidth(str) Width of the bars. Default is boxw(3.2).

labscale(num) Scaling factor of the labels. Default is labscale(0.3333). Changing the value will change the relative
weights of the smaller and higher values. This is an advanced option therefore use with caution.

Link values

valsize(str) The size of the displayed values. Default is vals(1.5).

valprop Scale the values based on the relative flows.

valscale(num) Scale factor of valprop. Default value is valscale(0.3333). Advance option, use carefully.

novalues Hide the values.

novalright Hide values on the right. Cannot be combined with novall.

novalleft Hide values on the left. Cannot be combined with novalr.

valcondition(num) This option can be specified to only display values >=num, e.g. valcond(100) implies >= 100. This option
can be used to reduce the number of labels displayed especially if there are several very small categories that might make the figure look messy.

format(str) The format of the displayed values. Default is format(%12.0f).

Column titles

ctitles(list) Give a list of column names. Names can either be defined as ctitle("name1 name2 name3 ...") or if there are spaces in
names as ctitle("My name1" "My name2" "My name3" "..."). Please make sure names are not very long and match the number of columns.

ctsize(num) The size of the column titles. Default is cts(2.5).

ctgap(num) The gap of the column titles. Default is ctg(0).

ctposition(bot|top) The position of column titles. No option defaults to ctpos(bot). Might still need adjustment via ctgap().

Miscellaneous

offset(num) The value, in percentage of x-axis width, to extend the x-axis on the right-hand side. Default is offset(0).
This option is highly useful especially if labels are rotated with custom positions.

title(), subtitle(), note() These are standard twoway graph options.

scheme(), name(), saving() These are standard twoway graph options.

xsize(), ysize() These standard twoway options can be used to space out the layers.
This is particularly helpful if several layers are plotted.

Dependencies

The palette package (Jann 2018, 2022) is required for sankey:

ssc install palettes, replace
ssc install colrspace, replace

Even if you have these installed, it is highly recommended to regularly check for updates.

Examples

See GitHub for examples.

Version history

- 1.71 : Fixed a bug where from() and to() value labels were overwriting each other.
- 1.7 : Fixed valcond() dropping bar values, and fixed ctitles color to black. Added percent (beta), ctpos().
- 1.61 : Adding saving() option.
- 1.6 : Rewrite of core routines. sortby() split into sort1() and sort2(). New option stock added.
- 1.51 : Add a string check for from() and by() variables.
- 1.5 : Added labprop, valprop, labscale(), valnoright, valnoleft, sortby(, reverse).
- 1.4 : Fixed the unbalanced panels. Fixed gaps between categories. Add column labels option. Added custom colors option.
- 1.3 : Node bundling added to align nodes across groups. Options sortby() and boxwidth() added.
- 1.21 : Bug fixes for 1.2. labcolor() added.
- 1.2 : Unbalanced in-coming and out-going groups now properly displace. Groups ending and starting in the middle now allowed.
- 1.1 : Enhancements. valformat() renamed to format(). offset added to displace x-axis range.
- 1.0 : First version.

Package details

Version : sankey v1.71
This release : 15 Jan 2024
First release: 08 Dec 2022
Repository : GitHub
Keywords : Stata, graph, sankey
License : MIT

Author : Asjad Naqvi
E-mail : asjadnaqvi@gmail.com
Twitter : @AsjadNaqvi

Feedback

Please submit bugs, errors, feature requests on GitHub by opening a new issue.

References

Jann, B. (2018). Color palettes for Stata graphics. The Stata Journal 18(4): 765-785.

Jann, B. (2022). Color palettes for Stata graphics: an update. University of Bern Social Sciences Working Papers No. 43.

Other visualization packages

arcplot, alluvial, bimap, bumparea, bumpline, circlebar, circlepack, clipgeo, delaunay, joyplot,
marimekko, sankey, schemepack, spider, streamplot, sunburst, treecluster, treemap