Skip to main content

19  Sankey diagrams

library(rtemis.draw)

draw_sankey() takes a data frame of directed links with source, target, and value columns. Node names are derived from the unique values of source and target; no separate node list is needed. Rows with the same source and target are summed into one link, and each link runs in a gradient from the color of the node it leaves to the color of the node it enters (link_color). A missing, infinite, or negative value, or links that form a cycle, stop with an error naming the row or the cycle. The chart is built by @rtemis/draw’s Sankey builder, which rtemislive also uses.

19.1 A randomized trial

The first example is a synthetic participant flow of a randomized trial, in the form of a CONSORT diagram: of 1000 people screened, some are ineligible or decline, the rest are randomized to two arms, and each participant completes the trial, withdraws, or is lost to follow-up.

trial <- read.csv(text = "
source,target,value
Screened,Ineligible,310
Screened,Declined,140
Screened,Randomized,550
Randomized,Treatment,275
Randomized,Control,275
Treatment,Completed,228
Treatment,Withdrew,30
Treatment,Lost to follow-up,17
Control,Completed,232
Control,Withdrew,25
Control,Lost to follow-up,18
")
trial
       source            target value
1    Screened        Ineligible   310
2    Screened          Declined   140
3    Screened        Randomized   550
4  Randomized         Treatment   275
5  Randomized           Control   275
6   Treatment         Completed   228
7   Treatment          Withdrew    30
8   Treatment Lost to follow-up    17
9     Control         Completed   232
10    Control          Withdrew    25
11    Control Lost to follow-up    18

A node’s column counts the links on the longest path to it from a node with no incoming links. node_align = "left" keeps that column for nodes with no outgoing links, so the excluded participants stay beside the randomized ones:

draw_sankey(trial, node_align = "left", title = "Participant flow")

19.2 An energy balance

A node that is a target in one row and a source in another sits between them, so flows chain through any number of stages. The second example is a synthetic energy balance in the form of national energy flow charts, with illustrative values in exajoules: primary sources feed electricity generation or the end-use sectors, and each sector’s input ends as useful energy or losses. With the default node_align = "justify", nodes with no outgoing links, here useful energy and losses, sit in the last column.

energy <- read.csv(text = "
source,target,value
Solar,Electricity,0.9
Wind,Electricity,1.5
Hydro,Electricity,0.8
Nuclear,Electricity,8.0
Coal,Electricity,8.5
Coal,Industrial,1.0
Natural gas,Electricity,13.0
Natural gas,Residential,5.0
Natural gas,Commercial,3.5
Natural gas,Industrial,10.0
Natural gas,Transportation,1.5
Oil,Residential,1.0
Oil,Commercial,1.0
Oil,Industrial,8.0
Oil,Transportation,25.0
Biomass,Electricity,0.4
Biomass,Residential,0.5
Biomass,Industrial,2.3
Biomass,Transportation,1.6
Electricity,Residential,5.1
Electricity,Commercial,4.6
Electricity,Industrial,3.4
Electricity,Transportation,0.1
Electricity,Losses,19.9
Residential,Useful energy,7.3
Residential,Losses,4.3
Commercial,Useful energy,5.9
Commercial,Losses,3.2
Industrial,Useful energy,12.4
Industrial,Losses,12.3
Transportation,Useful energy,5.9
Transportation,Losses,22.3
")
draw_sankey(energy, node_gap = 14, title = "Energy flow (EJ)")

19.3 Vertical layout

orient = "vertical" draws the flow from top to bottom, the layout of a CONSORT diagram, and node_width and node_gap set the thickness of the nodes and the space between them. Vertical labels wrap to the width of their node. The example assigns both dropout reasons the target “Dropped out”, and draw_sankey() sums each arm’s two rows into one link:

dropout <- trial
dropout$target[dropout$target %in% c("Withdrew", "Lost to follow-up")] <- "Dropped out"
draw_sankey(
  dropout,
  orient = "vertical",
  node_align = "left",
  node_width = 14,
  node_gap = 12
)

19.4 Configuration

setup_SankeyConfig() describes a Sankey diagram by its link columns:

config <- setup_SankeyConfig(source = "source", target = "target",
                             value = "value", node_align = "left")
draw(config, data = trial)
© 2026 E.D. Gennatas