Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 44 ยท Layouts and Hierarchies

Chord Diagrams and Binning

Draw relationships between groups with d3.chord and d3.ribbon, and group numbers into a histogram with d3.bin, thresholds and bar rendering.

Two more layouts complete the toolbox of this chapter. The chord layout shows flows or relationships between groups (who trades with whom). The bin layout counts how many values fall into each interval, the basis of every histogram. They look very different, but both follow the same pattern: feed in data, receive objects with geometry, draw them yourself.

Chord diagrams

A chord diagram arranges groups around a circle and connects them with ribbons whose thickness shows the strength of the connection. The data is a square matrix: matrix[i][j] is the flow from group i to group j.

JavaScript
const names = ["Rail", "Road", "Air", "Sea"];
const matrix = [
  [ 0, 12,  4,  8],
  [10,  0,  6, 14],
  [ 3,  5,  0,  2],
  [ 9, 11,  1,  0]
];
const chords = d3.chord().padAngle(0.05).sortSubgroups(d3.descending)(matrix);

d3.chord() returns an array of chord objects, with a .groups array attached:

  • chords.groups has one entry per row with index, startAngle, endAngle and value: draw these as outer arcs with d3.arc().
  • Each chord has source and target, both with index, startAngle, endAngle and value: draw these with d3.ribbon().

The matrix may be asymmetric. Use d3.chordDirected() (and d3.ribbonArrow()) when the direction of each flow matters.

Transport chord diagram

Notice the label trick: each label is rotated to its angle, moved outward, and flipped 180 degrees on the left half of the circle so text is never upside down.

Chord diagrams are striking but hard to read exactly. They work best with fewer than about ten groups, and you should provide hover highlighting or a table with the actual values.

Binning data into a histogram

A histogram groups numbers into consecutive intervals ("bins") and counts the items per interval. d3.bin() does exactly this and returns an array of bins; each bin is an array of the values it contains, with x0 and x1 for its edges.

JavaScript
const values = [2, 3, 3, 4, 5, 5, 5, 6, 7, 9, 10, 10, 12];
const bins = d3.bin().domain([0, 15]).thresholds(5)(values);
// each bin: [values...] with .x0 and .x1

Options:

  • .domain([min, max]) sets the range covered (default is the extent of the data).
  • .thresholds(n) suggests roughly n bins with "nice" edges; pass an array such as [0, 5, 10, 20] for exact edges; or a function like d3.thresholdSturges (default), d3.thresholdScott or d3.thresholdFreedmanDiaconis.
  • .value(d => d.age) lets you bin objects by a field.

Bins are half-open: a value equal to an edge belongs to the bin that starts at that edge, except for the very last bin which includes its upper edge.

A histogram from d3.bin

The total of the bin lengths equals the number of values, which is a handy sanity check. A bin width of 4 units shows the bell shape clearly; try changing thresholds(15) to thresholds(5) or thresholds(40) to see how bin count changes the story.

Choosing the number of bins

Too few bins hide the shape; too many make noise. Sturges' rule (the default) suits smaller, roughly normal data; Freedman-Diaconis adapts to the spread and works better for big or skewed data. When in doubt, let users change the bin count with a slider (see Mouse Events and Tooltips for handling input).

Binning in two dimensions

D3 also offers d3.contourDensity() (smoothed density contours for scatter plots) and d3.hexbin (a separate plugin). The idea is the same as d3.bin: summarise too many points into regions so the chart stays readable. For simple grids, do your own binning with d3.rollup(points, v => v.length, d => Math.floor(d.x / 10), d => Math.floor(d.y / 10)).

Common mistakes

  • Using a fixed .domain() that does not cover all values: values outside are dropped silently.
  • Forgetting that thresholds(n) is only a hint: you may get more or fewer bins. Pass an explicit array when you need exact edges.
  • Drawing histogram bars with a band scale. Bins are continuous intervals, so use a linear scale and the x0 and x1 of each bin.
  • In a chord diagram, passing a non-square matrix.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What shape of data does d3.chord expect?

    matrix[i][j] is the flow from group i to group j, so the matrix must be square.
  2. 2. Which generator draws the connections between groups in a chord diagram?

    d3.ribbon turns a chord's source and target angles into a ribbon path. d3.arc draws the outer group arcs.
  3. 3. What is each element of the array returned by d3.bin()?

    Bins are arrays of values; their length is the count, and x0 and x1 hold the edges.
  4. 4. How do you set exact bin edges?

    Passing an array to thresholds sets the edges exactly; a number is only a suggestion.

Summary

  • d3.chord turns a square matrix into group arcs and ribbons; draw them with d3.arc and d3.ribbon.
  • d3.bin counts values per interval; each bin carries x0 and x1.
  • Choose thresholds with care and keep a sanity check on totals.
  • Both layouts produce geometry, and you decide the final look.

Next: Transitions