Skip to main content

​
Overview

The chordDiagramLand() function creates circular chord diagrams to visualize one-step land use and cover (LUC) transitions between two time points. Chord diagrams are ideal for showing the magnitude and direction of transitions in a compact, circular layout.

​
Function Signature

chordDiagramLand(
  dataset,
  legendtable,
  legposition = c(x = -1.3, y = 0),
  legtitle = "Categories",
  sectorcol = "gray80",
  area_km2 = TRUE,
  legendsize = 1,
  y.intersp = 1,
  x.margin = c(-1, 1)
)

​
Parameters

​
dataset
data.frame
required
A table of 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).
​
legposition
numeric vector
default:"c(x = -1.3, y = 0)"
A named vector containing the x and y coordinates for the legend position.
​
legtitle
character
default:"Categories"
The title displayed above the legend.
​
sectorcol
character
default:"gray80"
The color of the external sector arcs that contain the year labels.
​
area_km2
logical
default:"TRUE"
If TRUE, transitions are shown in km²; if FALSE, in pixel counts.
​
legendsize
numeric
default:"1"
Font size multiplier for the legend text.
​
y.intersp
numeric
default:"1"
Character interspacing factor for vertical spacing in the legend.
​
x.margin
numeric vector
default:"c(-1, 1)"
Additional horizontal space (blank area) on the left or right of the circle for the legend. Passed to circlize::circos.par() as canvas.xlim.

​
Return Value

Creates a chord diagram plot showing:
  • Circular sectors representing land use categories at two time points
  • Ribbons (chords) connecting categories, showing transitions
  • Ribbon width proportional to transition area
  • Directional arrows indicating the flow direction
  • Year labels on external arcs

​
Usage Examples

​
Basic Chord Diagram

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 chord diagram
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend
)

​
Customizing Legend Position

Adjust legend placement for better visibility: 
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend,
  legposition = c(x = -1.5, y = 0.5),  # Move legend up and left
  legendsize = 1.2,                     # Larger legend text
  y.intersp = 1.5                       # More spacing between items
)

​
Adjusting Canvas Margins

Provide more space for the legend: 
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend,
  x.margin = c(-1.5, 1),  # More space on the left
  legposition = c(x = -1.8, y = 0)
)

​
Custom Sector Color

Change the color of the year arc sectors: 
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend,
  sectorcol = "lightblue"  # Custom sector color
)

​
Saving Chord Diagrams

Chord diagrams are base R graphics. Save using standard R graphics devices: 
# Save as PNG
png("chord_diagram.png", width = 3000, height = 3000, res = 300)
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend
)
dev.off()

# Save as PDF
pdf("chord_diagram.pdf", width = 10, height = 10)
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend
)
dev.off()

​
Interpretation Guide

  • Sector size: Proportional to the total area of each category at each time point
  • Ribbon width: Proportional to the transition area from one category to another
  • Ribbon color: Matches the source category color
  • Arrows: Indicate the direction of change from source to target
  • Outer labels: Category names at each time point
  • Outer arcs: Year labels showing the time period
Chord diagrams work best for one-step transitions. For multi-step analysis, use sankeyLand() instead.

​
Advanced Customization

​
Using Pixel Counts Instead of Area

chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend,
  area_km2 = FALSE  # Show pixel counts
)
Adjust legposition and x.margin together to find the optimal layout for your legend and diagram.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us