Skip to main content

​
Overview

The sankeyLand() function creates interactive Sankey diagrams to visualize one-step or multi-step land use and cover (LUC) transitions. Sankey diagrams are ideal for showing flows and transitions between categories across time periods.

​
Function Signature

sankeyLand(dataset, legendtable, iterations = 0)

​
Parameters

​
dataset
data.frame
required
A table of multi-step (lulc_Multistep) or one-step transitions (lulc_Onestep) generated by contingencyTable().
​
legendtable
data.frame
required
A table containing the LUC legend items and their respective colors (tb_legend). Must include columns: categoryValue, categoryName, and color.
​
iterations
numeric
default:"0"
Number of iterations in the diagram layout for computation of the depth (y-position) of each node. See networkD3::sankeyNetwork() for details.

​
Return Value

Returns an interactive HTML widget (Sankey diagram) created using the networkD3 package. The diagram shows:
  • Nodes representing land use categories at each time point
  • Links showing the flow/transition between categories
  • Link width proportional to the transition area (km²)
  • Color coding based on the source category

​
Usage Examples

​
One-Step Sankey Diagram

Visualize transitions between the first and last year only: 
library(OpenLand)

# Prepare the legend
SL_2002_2014$tb_legend$categoryName <- factor(
  c("Ap", "FF", "SA", "SG", "aa", "SF", "Agua", "Iu", "Ac", "R", "Im"),
  levels = c("FF", "SF", "SA", "SG", "aa", "Ap", "Ac", "Im", "Iu", "Agua", "R")
)

SL_2002_2014$tb_legend$color <- c(
  "#FFE4B5", "#228B22", "#00FF00", "#CAFF70", "#EE6363", "#00CD00",
  "#436EEE", "#FFAEB9", "#FFA54F", "#68228B", "#636363"
)

# Create one-step Sankey diagram
sankeyLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend
)

​
Multi-Step Sankey Diagram

Visualize transitions across all time intervals: 
# Create multi-step Sankey diagram
sankeyLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  iterations = 32
)
Multi-step Sankey diagrams show the complete temporal evolution of land use patterns, making it easier to identify persistent categories and sequential transitions.

​
Customization

​
Adjusting Layout

The iterations parameter controls the vertical positioning of nodes: 
# More iterations = better vertical spacing
sankeyLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  iterations = 100  # Higher value for complex diagrams
)

​
Color Scheme

Colors are determined by the legendtable$color column, ordered by category names: 
# Use custom colors
SL_2002_2014$tb_legend$color <- c(
  "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728",
  "#9467bd", "#8c564b", "#e377c2", "#7f7f7f",
  "#bcbd22", "#17becf", "#aec7e8"
)

sankeyLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend
)

​
Saving Sankey Diagrams

Since Sankey diagrams are HTML widgets, save them using htmlwidgets: 
library(htmlwidgets)

# Create the diagram
my_sankey <- sankeyLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend
)

# Save as HTML
saveWidget(my_sankey, "sankey_diagram.html")

​
Interpretation Guide

  • Node height: Represents the total area of a category at a given time point
  • Link width: Proportional to the transition area between categories
  • Link color: Matches the source category color
  • Interactive: Hover over nodes and links to see exact values
For publications, capture screenshots of the interactive diagram or export to HTML and embed in supplementary materials.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us