Introduction to chorddiag

The chorddiag package in R is a powerful tool for creating interactive chord diagrams using the D3 JavaScript library. Chord diagrams are excellent for visualizing complex relationships between entities, making them useful in various fields such as data science, biology, and social network analysis.

Key Features:

Create interactive chord diagrams
Customize colors, labels, and tooltips
Support for directional and bipartite diagrams

✍️ Author: Matthias Flor

📘 Documentation: GitHub

⭐️ GitHub Stars: 150+

Installation

Install the chorddiag package from GitHub using the devtools package:

# install.packages("devtools")
devtools::install_github("mattflor/chorddiag")

Basic Usage

The main function in the chorddiag package is chorddiag(). Here’s a basic example:

library(chorddiag)

m <- matrix(
   c(
      11975, 5871, 8916, 2868,
      1951, 10048, 2060, 6171,
      8010, 16145, 8090, 8045,
      1013, 990, 940, 6907
   ),
   byrow = TRUE,
   nrow = 4, ncol = 4
)
groupNames <- c("black", "blonde", "brown", "red")

interactive_plot <- chorddiag(m, groupNames = groupNames)

# Save the plot as an HTML file
htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-1.html")

Key Features and Customization

Customizing Colors

Use the groupColors parameter to set custom colors for your chord diagram:

custom_colors <- c("#1f77b4", "#ff7f0e", "#2ca02c", "#d62728")
interactive_plot <- chorddiag(m, groupNames = groupNames, groupColors = custom_colors)

htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-2.html")

Adjusting Layout

Modify the diagram’s layout using parameters like margin, groupThickness, and groupPadding:

interactive_plot <- chorddiag(m,
   groupNames = groupNames,
   margin = 100,
   groupThickness = 0.2,
   groupPadding = 3
)

htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-3.html")

Customizing Labels

Enhance readability by adjusting label properties:

interactive_plot <- chorddiag(m,
   groupNames = groupNames,
   groupnamePadding = 60, # put more space between the group names and the diagram
   groupnameFontsize = 25 # increase the font size of the group names
)

htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-4.html")

Tooltips and Interactivity

Customize tooltips for better user interaction:

interactive_plot <- chorddiag(m,
   groupNames = groupNames,
   tooltipGroupConnector = " to ", # change the connector between the group names
   tooltipUnit = " people", # add a unit to the tooltip values
   precision = 2 # set the number of decimal places in the tooltip values
)

htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-5.html")

Bipartite Diagrams

chorddiag supports bipartite chord diagrams, useful for contingency tables:

# Load the Titanic dataset
data(Titanic)

# Convert the 4D array to a 2D matrix (Class vs. Survived)
titanic_matrix <- apply(Titanic, c(1, 4), sum)

# Create the bipartite chord diagram
interactive_plot <- chorddiag(titanic_matrix,
   type = "bipartite",
   groupnameFontsize = 12,
   groupnamePadding = 10,
   tooltipGroupConnector = " in "
)

# Save the plot as an HTML file
htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-6.html")

Customizing Tick Labels

Adjust tick labels for better data representation:

interactive_plot <- chorddiag(m,
   groupNames = groupNames,
   tickInterval = 2000, # set the interval between ticks
   ticklabelFontsize = 8 # set the font size of the tick labels
)

htmlwidgets::saveWidget(interactive_plot, "../HtmlWidget/chord_diagram-7.html")

Going further

If you want to go further with chord diagrams, you might be interested in:

the circlize package for static circular visualization

Introduction to arcs

How to use circos.arc to draw arcs between entities, resulting in a chord diagram.

Basic chord diagram

How to build a basic chord diagram from an edge list or an adjacency matrix with R and the circlize package.

Customized chord diagram

Build links manually to allow more flexiility on the display.

the dedicated section on chord diagrams in R

Learn more about chord diagrams in R

Create Interactive Chord Diagrams with chorddiag