Version Compatibility

Reference examples tested with: ggalluvial 0.12+, networkD3 0.4+, plotly 4.10+, consort 0.2+ (CONSORT diagrams), pySankey 0.0.1+.

Before using code patterns, verify installed versions match. If versions differ:

• R: packageVersion('<pkg>') then ?function_name
• Python: pip show <package> then help(module.function)

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Flow and Transition Plots

"Show how things flow between categories" -> Render entities as ribbons whose width encodes count, flowing between ordered columns of categories. Sankey emphasizes total flow magnitude; alluvial emphasizes per-entity continuity (each row's path is traceable); CONSORT formalizes the trial-filtering convention. The decision space: which method (Sankey vs alluvial vs CONSORT), how to order categories within each column, and whether to highlight specific entity trajectories.

• R: ggalluvial::geom_alluvium, networkD3::sankeyNetwork, consort::consort_plot
• Python: plotly.graph_objects.Sankey, pySankey

The Single Most Important Modern Insight -- Sankey vs Alluvial Are Different

Sankey plots show flow from sources to sinks; each ribbon represents an aggregate count. The horizontal direction is "flow." Use for energy flows, web-traffic funnels, cohort dropouts.

Alluvial plots track individual entities through multiple ordered category columns (axes). Each row of input data becomes a continuous ribbon; intersections at each axis show counts in each category. Use for cell-state transitions across timepoints, drug-response trajectories, longitudinal class changes.

A Sankey shows "100 cells became neuron, 50 became glia"; an alluvial shows "of the 100 that became neurons at t2, 80 came from the proliferating pool at t1." Different encoding, different scientific story.

Decision Tree by Use Case

Use case	Recommended	Tool
Single timepoint, source-to-sink flow	Sankey	networkD3, plotly
Multi-timepoint entity trajectories	Alluvial	ggalluvial
Clinical trial patient flow	CONSORT (formal vertical box-and-arrow)	consort R package
Variant filtering pipeline	CONSORT-style flow	consort or manual diagrammeR
Cell-state transitions (scRNA timepoints)	Alluvial OR Sankey if 2 timepoints	ggalluvial
Drug response class changes	Alluvial	ggalluvial
Gene-set membership across conditions	UpSet (alternative)	data-visualization/upset-plots

ggalluvial -- Modern R Default for Alluvial

Goal: Visualize entity (e.g., cell, patient) trajectories across multiple ordered axes with ribbon-width = count.

Approach: Reshape to "lodes" (long) format with one row per entity-stratum, or "alluvia" (wide) format with one row per entity; use geom_alluvium for ribbons and geom_stratum for column boxes.

library(ggalluvial)
library(ggplot2)

# Wide (alluvia) format: one row per entity
df_wide <- data.frame(
    entity_id = 1:1000,
    t1 = sample(c('A', 'B', 'C'), 1000, replace = TRUE),
    t2 = sample(c('A', 'B', 'C'), 1000, replace = TRUE),
    t3 = sample(c('A', 'B', 'C'), 1000, replace = TRUE))

ggplot(df_wide, aes(axis1 = t1, axis2 = t2, axis3 = t3)) +
    geom_alluvium(aes(fill = t1), alpha = 0.7, width = 1/6) +
    geom_stratum(width = 1/6, fill = 'grey90', color = 'black') +
    geom_text(stat = 'stratum', aes(label = after_stat(stratum)), size = 3) +
    scale_x_discrete(limits = c('t1', 't2', 't3')) +
    scale_fill_manual(values = c('#0072B2', '#D55E00', '#009E73')) +
    labs(y = 'Entities', x = NULL) +
    theme_classic()

aes(fill = t1) colors each ribbon by its starting class — common pattern for "where did this end up cluster come from?" stories.

networkD3 -- Interactive Sankey

library(networkD3)

# Nodes and links
nodes <- data.frame(name = c('Source A', 'Source B', 'Sink X', 'Sink Y', 'Sink Z'))
links <- data.frame(source = c(0, 0, 1, 1),
                    target = c(2, 3, 3, 4),
                    value  = c(40, 30, 50, 20))

sankeyNetwork(Links = links, Nodes = nodes,
              Source = 'source', Target = 'target', Value = 'value',
              NodeID = 'name',
              colourScale = JS('d3.scaleOrdinal(d3.schemeCategory10);'),
              fontSize = 12, nodeWidth = 30, height = 400, width = 700)

networkD3 produces interactive HTML — drag nodes, hover for values. For static publication figure, screenshot or export via webshot2.

plotly Sankey (Python)

import plotly.graph_objects as go

fig = go.Figure(go.Sankey(
    node=dict(label=['Source A', 'Source B', 'Sink X', 'Sink Y', 'Sink Z'],
              color=['#0072B2', '#56B4E9', '#D55E00', '#E69F00', '#009E73']),
    link=dict(source=[0, 0, 1, 1],
              target=[2, 3, 3, 4],
              value=[40, 30, 50, 20],
              color=['rgba(0,114,178,0.4)'] * 4)))
fig.update_layout(title='Flow', font_size=12)
fig.write_html('sankey.html')
fig.write_image('sankey.pdf')           # requires Kaleido (NOT orca; orca is EOL)

CONSORT Diagrams -- The Formal Trial-Flow Standard

CONSORT 2010 (Schulz 2010 BMJ 340:c332) is the canonical clinical-trial flow diagram. The consort R package implements the structure:

library(consort)

# Trial enrollment flow
g <- add_box(txt = c('Assessed for eligibility (n=200)'))
g <- add_side_box(g, txt = c('Excluded (n=50)\n  - Not meeting criteria (n=30)\n  - Declined (n=15)\n  - Other (n=5)'))
g <- add_box(g, txt = c('Randomized (n=150)'))
g <- add_split(g, txt = c('Allocated to intervention (n=75)\n  - Received as allocated (n=70)\n  - Did not receive (n=5)',
                          'Allocated to control (n=75)\n  - Received as allocated (n=73)\n  - Did not receive (n=2)'))
g <- add_box(g, txt = c('Lost to follow-up (n=2)\nDiscontinued (n=3)',
                        'Lost to follow-up (n=1)\nDiscontinued (n=2)'))
g <- add_box(g, txt = c('Analysed (n=75)\nExcluded from analysis (n=0)',
                        'Analysed (n=75)\nExcluded from analysis (n=0)'))
plot(g)

CONSORT is a required element in randomized trial publication (CONSORT 2010 statement, item 13a).

Per-Method Failure Modes

Sankey used when alluvial is appropriate

Trigger: Multi-timepoint cell-state data plotted as Sankey instead of alluvial.

Mechanism: Sankey collapses to source-sink summary; loses entity-trajectory continuity.

Symptom: Reader sees "cluster A → 50% to B, 50% to C" but cannot trace individual trajectories.

Fix: Use ggalluvial for multi-axis trajectories; Sankey for single-step source-to-sink.

Category ordering within column not specified

Trigger: Default ggalluvial ordering by frequency.

Mechanism: Categories shuffle position across columns; ribbons cross excessively.

Symptom: Visual spaghetti; hard to follow.

Fix: Set explicit factor levels (factor(t1, levels = c('A', 'B', 'C'))) AND consider ggalluvial's lode.guidance to minimize crossings.

Ribbon coloring by destination instead of origin

Trigger: geom_alluvium(aes(fill = t3)) for a "where did these come from" story.

Mechanism: Color encodes the wrong axis; readers misinterpret.

Symptom: Story is "where did final cluster Z come from" but ribbons are colored by Z — every ribbon to Z is the same color.

Fix: aes(fill = t1) if origin matters; aes(fill = t3) if destination matters.

CONSORT diagram missing required boxes

Trigger: Skipping "Lost to follow-up" or "Excluded from analysis" boxes.

Mechanism: CONSORT 2010 requires reporting at each stage.

Symptom: Submission flagged for non-compliance with CONSORT 2010 item 13a.

Fix: Use consort package which scaffolds the required structure; cross-check against CONSORT 2010 statement.

plotly Sankey value sum mismatch

Trigger: Source-to-target sums don't balance.

Mechanism: plotly Sankey requires conservation: sum of in-flows = sum of out-flows at each non-terminal node.

Symptom: Layout renders but node sizes look wrong; ribbons stretch/compress incorrectly.

Fix: Verify upstream data: per-node sum(value where target=node) == sum(value where source=node) for internal nodes.

Static export of plotly Sankey fails silently

Trigger: fig.write_image('sankey.pdf') without kaleido installed.

Mechanism: plotly defaults to Kaleido for static export since orca EOL; kaleido is optional dependency.

Symptom: No file written; no error in some plotly versions.

Fix: pip install kaleido; verify with import kaleido.

Reconciliation: When Implementations Differ

Pattern	Cause	Action
ggalluvial and networkD3 show different orderings	Different default stratum/node ordering	Set explicit factor levels / node order
CONSORT box counts don't sum	Box-content arithmetic error	Audit each box; consort package enforces structure
Cells appear/disappear between alluvial axes	Missing data in some timepoints	Decide: drop entities with NA; OR add "Missing" category

Quantitative Thresholds

Threshold	Value	Source
Max categories per column for legibility	5-7	Visualization practical
Max axes for alluvial	4-5	Above this ribbons too crossed
CONSORT requirement	Required for RCTs	Schulz 2010 CONSORT 2010

Common Errors

Error / symptom	Cause	Solution
Excessive ribbon crossing	Categories unordered	Explicit factor levels; lode.guidance
Trajectories not traceable	Sankey used instead of alluvial	Switch to ggalluvial
CONSORT non-compliant	Missing required boxes	Use consort package
Sankey node sizes wrong	Flow not conserved	Audit source-target sums
plotly static export blank	kaleido not installed	pip install kaleido
Color story unclear	Wrong axis for fill	Decide origin vs destination story

References

• Brunson J. 2020. ggalluvial: Layered grammar for alluvial plots. J Open Source Softw 5(49):2017.
• Sankey MH. 1898. The thermal efficiency of steam engines. Proc Inst Civil Eng 134:278-312. (origin)
• Schulz KF, Altman DG, Moher D; CONSORT Group. 2010. CONSORT 2010 Statement: updated guidelines for reporting parallel group randomised trials. BMJ 340:c332.
• Riehmann P, Hanfler M, Froehlich B. 2005. Interactive Sankey diagrams. IEEE Symp Information Visualization.

Related Skills

• data-visualization/upset-plots - Alternative for set-intersection rather than flow
• clinical-biostatistics/trial-reporting - CONSORT diagrams in trial publication
• single-cell/trajectory-inference - Cell-state transition data for alluvial
• workflows/biomarker-pipeline - Pipeline filtering flows