chord()

chord(matrix)

Computes the chord layout for the specified square matrix of size n×n, where the matrix represents the directed flow amongst a network (a complete digraph) of n nodes. The given matrix must be an array of length n, where each element matrix[i] is an array of n numbers, where each matrix[i][j] represents the flow from the ith node in the network to the jth node. Each number matrix[i][j] must be nonnegative, though it can be zero if there is no flow from node i to node j. From the Circos tableviewer example:

var matrix = [
  [11975,  5871, 8916, 2868],
  [ 1951, 10048, 2060, 6171],
  [ 8010, 16145, 8090, 8045],
  [ 1013,   990,  940, 6907]
];

The return value of chord(matrix) is an array of chords, where each chord represents the combined bidirectional flow between two nodes i and j (where i may be equal to j) and is an object with the following properties:

• source - the source subgroup
• target - the target subgroup

Each source and target subgroup is also an object with the following properties:

• startAngle - the start angle in radians
• endAngle - the end angle in radians
• value - the flow value matrix[i][j]
• index - the node index i
• subindex - the node index j

The chords are typically passed to d3.ribbon to display the network relationships. The returned array includes only chord objects for which the value matrix[i][j] or matrix[j][i] is non-zero. Furthermore, the returned array only contains unique chords: a given chord ij represents the bidirectional flow from i to j and from j to i, and does not contain a duplicate chord ji; i and j are chosen such that the chord’s source always represents the larger of matrix[i][j] and matrix[j][i]. In other words, chord.source.index equals chord.target.subindex, chord.source.subindex equals chord.target.index, chord.source.value is greater than or equal to chord.target.value, and chord.source.value is always greater than zero.

The chords array also defines a secondary array of length n, chords.groups, where each group represents the combined outflow for node i, corresponding to the elements matrix[i][0 … n - 1], and is an object with the following properties:

• startAngle - the start angle in radians
• endAngle - the end angle in radians
• value - the total outgoing flow value for node i
• index - the node index i

The groups are typically passed to d3.arc to produce a donut chart around the circumference of the chord layout.