lessR (version 4.5)

Flows: 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
)

Value

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

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.

Author

David W. Gerbing

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.

See Also

Chart for other Plotly-based charts in lessR, including type="bar", type="sunburst", "treemap", "pie", "radar", and "bubble". Histogram and Plot also create Plotly-based charts.

Examples

if (interactive()) { 
# 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)
}