*! version 1.0 16june2022 Maik Hamjediers

*! version 1.1 01july2022 Maik Hamjediers

*! version 1.11 16july2022 Maik Hamjediers

*! version 1.2	10nove2022 Maik Hamjediers

help for sankeyplot

Title

sankeyplot -- Sankey plot for visualizing flow between two or more domains of categorical variables

Syntax

sankeyplot varlist [if] [in] [, options]

If data is in long format:

sankeyplot varname clustervar domainvar [if] [in] , long [options]

Options
percent relative frequencies instead of absolute number of observations

points(#) draw flows via # points between bars (deafult is points(10))

missing plot missing values of varlist (default is to omit them)

force generate graph although variables in varlist have many levels

barwidth(#) width of bars (default is barwidth(0.1))

colors(colorstylelist) list of colors in the order of categories

flowcolors(colorstylelist) list of colors in the order of categories for the flows

opacity(#) controls the opacity of all colors

baroptions(barlook_options) change look of bars (applies to all bars)

flowoptions(area_options) change look of flows (applies to all flows)

Bar labels
blabel(vallabel|catlabel) adds labels to bars

blabformat(%fmt) barlabels: format label values per %fmt

blaboptions(textbox_options) barlabels: look of barlabels

Flow labels
flowlabel(left|right) adds labels to flows

flowlabsize(textsizestyle) flowlabels: size of text

flowlabcolor(colorstyle) flowlabels: color and opacity of text

flowlaborientation(orientationstyle) flowlabels: orientation of label

flowlabformat(%fmt) flowlabels: format label values per %fmt

twoway_options Any options documented in [G-3] twoway_options

Description

sankeyplot creates a sankey diagram, which visualizes flow of the values of one variable to another.

In the default setting, the command assumes that the data is given in a wide format (each variable presents a domain). The command takes two or more categorical variables as input, which should represent the same set of values across domains (e.g., waves or generations).

If the data that should be plotted is in a long format (obsverations represent domains), specify the long-option and three variables as the input: the categorical variable that should be plotted, an identifier of the clusters (e.g., pid), and a domain variable (e.g., wave).

Altough it is most common to visualize flows among variables with the same set of values, specifying two different set of values is also possible. Yet, note that the legend and colors will be based on the variable mentioned first in varlist. If two different variables are used it is recommended to use the options blabel(catlabel) and legend(off).

Options

percent specifies to plot the relative frequencies of the levels of the plotted variables. The default is to plot absolute frequencies.

points(#) specifies the number of points between bars through which the flows are drawn. The default are 10 points, with a larger number increasing the smoothness and computational time.

missing specifies to plot missing values in varlist as well. The default is to disregard them. Note that missing values can lead to an imbalance between start and end bars or they produce flows into empty bars. Instead of using missing, rather code missing values as distinct values in the underyling variables.

force overrules the default of not plotting variables with more than seven unique levels. Plotting variables with many levels likely impairs readability and might take relatively long.

barwidth(#) specifies the width of the bar. The default is barwidth(0.1); values greater than 0.5 are not allowed.

colors(colorstylelist) specifies the colors and opacity of the bars and flows. List the colors in the increasing order of the values of the plotted variables.

flowcolors(colorstylelist) allow to colors and opacity of flows, independently of the option colors(). List the colors in the increasing order of the values of the plotted variables.

opacity(#) specifies the opacity of the colors of bars and flows. The default is opacity(80).

baroptions(barlook_options) allows most of the barlook_options to change the look of the bars. Note that any specified option in baroptions() affect all bars; specifying for instance baroptions(color(navy)) overrides any specification of the above option colors() and depicts all bars in navy.

flowoptions(area_options) allows most of the area_options to change the look of the flows. Note that any specified option in flowoptions() affect all flows; specifying for instance flowoptions(color(navy)) overrides any specification of the above options colors() and flowcolors() and depicts all flows in navy.

blabel(vallabel|catlabel) adds either value-labels or the labels of the plotted categories to all bars. If vallabel and percent are specified, relative frequencies are presented in the bars; otherwise vallabel shows absolute frequencies.

blaboptions(textbox_options) allows to specify details about how the bar labels are presented via any options listed under textbox_options.

flowlabel(left|right) adds value-labels at the start or end of all flows. If flowlabel() and percent are specified, relative frequencies are presented in the flows; otherwise flowlabel() shows absolute frequencies.

flowlabformat(%fmt), flowlabsize(textsizestyle), flowlaborientation(orientationstyle) and flowlabcolor(colorstyle) specify details about how the flow labels are presented. See format, [G-4] textsizestyle, orientationstyle, and [G-4] colorstyle.

twoway_options allows for the inclusion of any additional graphing options such as titles, axes, added lines, etc.

Examples

Setup (click to run)

. clear

. set obs 987

. gen edu_0 = _n <= 500

. replace edu_0 = 2 if _n > 900

. gen edu_1 = runiformint(0,2)

. lab def edu 0 "Low Edu." 1 "Medium Edu." 2 "High Edu."

. lab val edu_0 edu_1 edu

Simple run

. sankeyplot edu_0 edu_1

Adding options (click to run)

. sankeyplot edu_0 edu_1, percent ///

. blabel(vallabel) blabformat(%3.1g) ///

. colors(gs6%70 gs10%70 gs14%70) ///

. legend(r(1) symx(*0.5) region(lc(white))) ///

. xlabel(0 "1st Gen." 1 "2nd Gen.") xtitle("") ///

. ylabel(,angle(0)) ytitle("Relative Frequencies") xsize(7) ///

. title("Educational Mobility Across Generations")

Highlighting the stream in the middle

. sankeyplot edu_0 edu_1, flowcol(none maroon none)

Plotting more than two variables

. sankeyplot edu_0 edu_1 edu_2

If data is in long format (click to run)

. sankeyplot edu_ id wave, long

Acknowledgements

Thanks to Daniele Florean, Navid Krueger, and Ferdinand Geissler for useful comments.

Author

Maik Hamjediers, Department of Social Sciences, Humboldt-Universität zu Berlin. mailto:maik.hamjediers@hu-berlin.de