Chord Diagram

Description

A chord diagram arranges a set of entities around the circumference of a circle, with arcs (chords) drawn between pairs of entities to represent the magnitude of their mutual relationship. The width of each chord at its endpoints encodes the flow or connection strength in each direction, making the diagram ideal for visualizing asymmetric flows (e.g., trade between countries, migration between regions, or dependencies between software modules).

Each entity occupies an arc segment on the circle whose angular span is proportional to its total flow (incoming plus outgoing). This means that larger entities command more visual space, and readers can compare total volumes by comparing arc lengths. The chords connecting entity pairs are colored (usually by source) and their width varies along their path if the flow is asymmetric — wider at the source end, narrower at the target end.

Chord diagrams are visually striking and can reveal dominant bilateral relationships, clusters of highly interconnected groups, and imbalances (where one entity sends much more than it receives). However, they become difficult to read with more than about 15 entities, as chords overlap and the circular layout makes angular comparisons less precise than linear ones. For large matrices, filtering to show only the top connections or providing hover-based highlighting is essential.

When to Use

• Visualizing flows between entities in a matrix (trade, migration, communication, dependencies)
• Showing both the total volume per entity and the bilateral relationship strengths
• Revealing dominant pathways and imbalances in a network of flows
• When the data is a square matrix (origin-destination table) with moderate entity count (5-15)

When NOT to Use

• When there are many entities (>15) — chords become unreadable; aggregate or use a heatmap
• When flows are unidirectional with clear stages — use a Sankey diagram instead
• When spatial layout matters (geographic data) — use a flow map
• When exact values are critical — angular and width comparisons are imprecise; use a table or bar chart

Anatomy

• Outer arcs: Colored arc segments around the circumference, one per entity. Arc length encodes total flow volume.
• Chords: Curved bands connecting pairs of entities inside the circle. Width at each endpoint encodes directional flow.
• Color encoding: Chords colored by source entity (or gradient from source to target color).
• Labels: Entity names positioned outside the circle adjacent to their arc.
• Tick marks: Optional graduation marks on the outer arcs showing quantitative scale.
• Gap: Small angular gaps between entities to visually separate them.

Variations

• Directed chord diagram: Chords taper from wider at the source to narrower at the target, making flow direction explicit.
• Grouped chord diagram: Entities are grouped into higher-level categories with visual separators between groups.
• Hierarchical chord diagram: Combines a hierarchical grouping on the outer ring with chords showing cross-group connections.
• Filtered chord diagram: Only the top-N connections are shown to reduce clutter.

Code Reference

// D3 Chord Diagram
import * as d3 from "d3";

const chord = d3.chord().padAngle(0.05).sortSubgroups(d3.descending);
const chords = chord(matrix);
const arc = d3.arc().innerRadius(innerRadius).outerRadius(outerRadius);
const ribbon = d3.ribbon().radius(innerRadius);

const svg = d3.select("#chart").append("svg")
  .attr("viewBox", [-width / 2, -height / 2, width, height]);

svg.append("g")
  .selectAll("path")
  .data(chords.groups).join("path")
  .attr("d", arc)
  .attr("fill", d => color(d.index));

svg.append("g")
  .selectAll("path")
  .data(chords).join("path")
  .attr("d", ribbon)
  .attr("fill", d => color(d.source.index))
  .attr("opacity", 0.6);