Creating a chord diagram
There are a number of layers to creating a chord diagram with d3, corresponding to d3's careful separation of data manipulation from data visualization. If you're going to not only create a chord diagram, but also update it smoothly, you'll need to clearly understand what each piece of the program does and how they interact.
First, the data-manipulation aspect. The d3 Chord Layout tool takes your data about the interactions between different groups and creates a set of data objects which contain the original data but are also assigned angle measurements . In this way, it is similar to the pie layout tool, but there are some important differences related to the increased complexity of the chord layout.
Like the other d3 layout tools, you create a chord layout object by calling a function (d3.layout.chord()), and then you call additional methods on the layout object to change the default settings. Unlike the pie layout tool and most of the other layouts, however, the chord layout object isn't a function that takes your data as input and outputs the calculated array of data objects with layout attributes (angles) set.
Instead, your data is another setting for the layout, which you define with the .matrix() method, and which is stored within the layout object. The data has to be stored within the object because there are two different arrays of data objects with layout attributes, one for the chords (connections between different groups), and one for the groups themselves. The fact that the layout object stores the data is important when dealing with updates, as you have to be careful not to over-write old data with new if you still need the old data for transitions.
var chordLayout = d3.layout.chord() //create layout object
.sortChords( d3.ascending ) //set a property
.padding( 0.01 ); //property-setting methods can be chained
chordLayout.matrix( data ); //set the data matrix
The group data objects are accessed by calling .groups() on the chord layout after the data matrix has been set. Each group is equivalent to a row in your data matrix (i.e., each subarray in an array of arrays). The group data objects have been assigned start angle and end angle values representing a section of the circle. This much is just like a pie graph, with the difference being that the values for each group (and for the circle as a whole) are calculated by summing up values for the entire row (subarray). The group data objects also have properties representing their index in the original matrix (important because they might be sorted into a different order) and their total value.
The chord data objects are accessed by calling .chords() on the chord layout after the data matrix has been set. Each chord represents two values in the data matrix, equivalent to the two possible relationships between two groups. For example, in @latortue09's example, the relationships are bicycle trips between neighbourhoods, so the chord that represents trips between Neighbourhood A and Neighbourhood B represents the number of trips from A to B as well as the number from B to A. If Neighbourhood A is in row a of your data matrix and Neighbourhood B is in row b, then these values should be at data[a][b] and data[b][a], respectively. (Of course, sometimes the relationships you're drawing won't have this type of direction to them, in which case your data matrix should be symmetric, meaning that those two values should be equal.)
Each chord data object has two properties, source and target, each of which is its own data object. Both the source and target data object have the same structure with information about the one-way relationship from one group to the other, including the original indexes of the groups and the value of that relationship, and start and end angles representing a section of one group's segment of the circle.
The source/target naming is kind of confusing, since as I mentioned above, the chord object represents both directions of the relationship between two groups. The direction that has the larger value determines which group is called source and which is called target. So if there are 200 trips from Neighbourhood A to Neighbourhood B, but 500 trips from B to A, then the source for that chord object will represent a section of Neighbourhood B's segment of the circle, and the target will represent part of Neighbourhood A's segment of the circle. For the relationship between a group and itself (in this example, trips that start and end in the same neighbourhood), the source and target objects are the same.
One final important aspect of the chord data object array is that it only contains objects where relationships between two groups exist. If there are no trips between Neighbourhood A and Neighbourhood B in either direction, then there will be no chord data object for those groups. This becomes important when updating from one dataset to another.
Second, the data-visualization aspect. The Chord Layout tool creates arrays of data objects, converting information from the data matrix into angles of a circle. But it doesn't draw anything. To create the standard SVG representation of a chord diagram, you use d3 selections to create elements joined to an array of layout data objects. Because there are two different arrays of layout data objects in the chord diagram, one for the chords and one for the groups, there are two different d3 selections.
In the simplest case, both selections would contain <path> elements (and the two types of paths would be distinguished by class). The <path>s that are joined to the data array for the chord diagram groups become the arcs around the outside of the circle, while the <path>s that are joined to the data for the chords themselves become the bands across the circle.
The shape of a <path> is determined by its "d" (path data or directions) attribute. D3 has a variety of path data generators, which are functions that take a data object and create a string that can be used for a path's "d" attribute. Each path generator is created by calling a d3 method, and each can be modified by calling it's own methods.
The groups in a standard chord diagram are drawn using the d3.svg.arc() path data generator. This arc generator is the same one used by pie and donut graphs. After all, if you remove the chords from a chord diagram, you essentially just have a donut diagram made up of the group arcs. The default arc generator expects to be passed data objects with startAngle and endAngle properties; the group data objects created by the chord layout works with this default. The arc generator also needs to know the inside and outside radius for the arc. These can be specified as functions of the data or as constants; for the chord diagram they will be constants, the same for every arc.
var arcFunction = d3.svg.arc() //create the arc path generator
//with default angle accessors
.innerRadius( radius )
.outerRadius( radius + bandWidth);
//set constant radius values
var groupPaths = d3.selectAll("path.group")
.data( chordLayout.groups() );
//join the selection to the appropriate data object array
//from the chord layout
groupPaths.enter().append("path") //create paths if this isn't an update
.attr("class", "group"); //set the class
/* also set any other attributes that are independent of the data */
groupPaths.attr("fill", groupColourFunction )
//set attributes that are functions of the data
.attr("d", arcFunction ); //create the shape
//d3 will pass the data object for each path to the arcFunction
//which will create the string for the path "d" attribute
The chords in a chord diagram have a shape unique to this type of diagram. Their shapes are defined using the d3.svg.chord() path data generator. The default chord generator expects data of the form created by the chord layout object, the only thing that needs to be specified is the radius of the circle (which will usually be the same as the inner radius of the arc groups).
var chordFunction = d3.svg.chord() //create the chord path generator
//with default accessors
.radius( radius ); //set constant radius
var chordPaths = d3.selectAll("path.chord")
.data( chordLayout.chords() );
//join the selection to the appropriate data object array
//from the chord layout
chordPaths.enter().append("path") //create paths if this isn't an update
.attr("class", "chord"); //set the class
/* also set any other attributes that are independent of the data */
chordPaths.attr("fill", chordColourFunction )
//set attributes that are functions of the data
.attr("d", chordFunction ); //create the shape
//d3 will pass the data object for each path to the chordFunction
//which will create the string for the path "d" attribute
That's the simple case, with <path> elements only. If you want to also have text labels associated with your groups or chords, then your data is joined to <g> elements, and the <path> elements and the <text> elements for the labels (and any other elements, like the tick mark lines in the hair-colour example) are children of the that inherit it's data object. When you update the graph, you'll need to update all the sub-components that are affected by the data.
Updating a chord diagram
With all that information in mind, how should you approach creating a chord diagram that can be updated with new data?
First, to minimize the total amount of code, I usually recommend making your update method double as your initialization method. Yes, you'll still need some initialization steps for things that never change in the update, but for actually drawing the shapes that are based on the data you should only need one function regardless of whether this
