Flows: Sankey Flow Diagram (2- or 3-Stage) with Plotly
In lessR: Less Code with More Comprehensive Results

Flows

R Documentation

Sankey Flow Diagram (2- or 3-Stage) with Plotly

Description

Create a Sankey flow diagram between source and target categories with weighted links that visualizes movement of volume between categorical stages. Supports either two stages (A -> B) or three stages (A -> B -> C). Flows (links) are colored by the leftmost source category and retain that color across all legs. Node fills can be neutral gray or (by default) the left/source nodes can inherit the flow colors while intermediate and right nodes remain gray. In RStudio, the visualization renders in the Viewer pane.

Usage

Flows(
  value,
  stage1,
  stage2,
  stage3 = NULL,
  data = d,
  # appearance
  title = NULL,
  fill = NULL,
  link_alpha = 0.55,
  nodes_gray = FALSE,
  neutral_gray = "gray80",
  border_gray  = "gray60",
  lift_y = 0,
  labels_size = 1.00,
  digits_d = 0
)

Arguments

`stage1`	Column name for the left (source) stage. May be given unquoted (recommended) or as a character string.
`stage2`	Column name for the middle (or right, in 2-stage) stage. Unquoted or character string.
`stage3`	Optional column name for the right stage (3-stage). If `NULL`, a 2-stage diagram is created. Unquoted or character string.
`value`	Column name with non-negative weights (e.g., counts, volume, tonnage) used to determine link thickness. Unquoted or character string.
`data`	A data frame containing the stages and the weight column. If `NULL`, the function will look for the columns in the calling environment.
`title`	Optional chart title. If `NULL`, a title is constructed from the provided stage names.
`fill`	Optional color range name or vector used for source categories. If `NULL` (default), the range is inherited from the current theme via `.color_range(.get_fill(getOption("theme")), n.x)`, where `n.x` is the number of unique `stage1` categories.
`link_alpha`	Numeric in \([0,1]\). Transparency for flows (links). Default `0.55`.
`nodes_gray`	Logical. If `FALSE` (default), left/source nodes are colored (matching their flows) and all other nodes are neutral gray. If `TRUE`, all nodes are neutral gray.
`neutral_gray`	Color for gray node fills. Defaults to `"gray80"`.
`border_gray`	Color for node borders. Defaults to `"gray60"`.
`lift_y`	Proportion of vertical shift of the displayed chart. Positive values lift the chart upward.
`labels_size`	Size of displayed labels, with 0.90 the default.
`digits_d`	Integer number of decimals for link values shown in the hover. Default `0`.

Details

Flow semantics
Flows is intended for directional flows where the width of each band represents the amount moving from one category to the next (e.g., supply chain, traffic, energy, user funnels). It is not a general association plot for arbitrary cross-tabulations without directional meaning. For hierarchical composition without directional flow, consider Chart with parameter type set to "sunburst", "treemap", "radar", or "pie" instead.

Color mapping
Flows are colored by the leftmost source category (stage1). In a 3-stage diagram, colors are carried from stage1 through stage2 to stage3 so each link retains its origin color. When nodes_gray = FALSE (default), only source nodes inherit the flow colors; middle and right nodes are neutral gray. When nodes_gray = TRUE, all nodes are gray. If fill is NULL, colors are drawn from the current lessR theme (getOption("theme")) via .get_fill() and .color_range().

Layout
Nodes are arranged in fixed columns: left = stage1, middle = stage2, right = stage3 (if provided). Vertical positions are spaced evenly within each column. The diagram prints automatically in interactive sessions and returns a Plotly htmlwidget (invisibly) for programmatic use.

Value

An object of class htmlwidget (Plotly). The widget prints automatically in interactive sessions; otherwise it is returned (invisibly) for further composition or saving.

Author(s)

David W. Gerbing

Examples


# Example data: Source -> Port -> Destination with volumes
SupplyChain <- data.frame(
  Source      = c("China","China","China","Germany","Germany",
                  "Brazil","Brazil","USA","USA"),
  Port        = c("Los Angeles","Seattle","Houston","New York","Baltimore",
                  "Miami","Houston","Los Angeles","Miami"),
  Destination = c("Portland","Chicago","Dallas","Boston","Philadelphia",
                  "Atlanta","Dallas","San Francisco","Atlanta"),
  Volume      = c(320,180,150,220,130,200,100,170,140)
)

# 3-stage: Source -> Port -> Destination (unquoted names)
Flows(Volume, Source, Port, Destination, data = SupplyChain)

# 2-stage: Source -> Port (sources colored; ports gray)
Flows(Volume, Source, Port, data = SupplyChain)

# All nodes neutral gray (flows still color by source)
Flows(Volume, Source, Port, Destination, data = SupplyChain,
       nodes_gray = TRUE, link_alpha = 0.6)

# Supply a specific range (overrides theme), show one decimal in hover
Flows(Volume, Source, Port, Destination, data = SupplyChain,
       fill = "blues", digits_d = 1)

lessR documentation built on Dec. 11, 2025, 5:07 p.m.