GPTomics/bio-data-visualization-flow-and-transition-plots

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