D3 · all subjects

d3-chord

26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Chord diagram example: hair color transitions

Example matrix showing transitions between hair colors (black, blond, brown, red): const matrix = [[11975, 5871, 8916, 2868], [1951, 10048, 2060, 6171], [8010, 16145, 8090, 8045], [1013, 990, 940, 6907]]. Each value represents the number of people who dyed their hair from one color to another, such as 5,871 people with black hair who dyed it blond.

Chord diagram ribbon visualization

Ribbons in a chord diagram connect nodes arranged along a circle's circumference. The starting and ending width of each ribbon is proportional to the flow value (number of transitions). The color of the ribbon is determined by the color with the larger of the two flow values being connected.

d3-chord submodules

The d3-chord module contains two main submodules: Chords (a layout for chord diagrams) and Ribbons (a shape primitive for chord diagrams).

d3-chord module overview

D3's chord layout represents flow using a square matrix of size n×n, where n is the number of nodes in the graph. Each value matrix[i][j] represents the flow from the ith node to the jth node. Each number must be nonnegative, though it can be zero if there is no flow. A chord diagram visualizes these transitions by arranging the population by starting color along the circumference of a circle and drawing ribbons between each color. The starting and ending width of the ribbon is proportional to the number of people that had the respective starting and ending color.

Chord diagram matrix structure

A chord diagram uses a square matrix where each row and column represents a node in the graph. The value at matrix[i][j] represents the flow from node i to node j. All values must be nonnegative. The matrix diagonal can represent self-loops or unchanged values (e.g., people who kept the same color).

chord.sortChords(compare) method

If compare is specified, sets the chord comparator to the specified function or null and returns the chord layout. If compare is not specified, returns the current chord comparator, which defaults to null. If the chord comparator is non-null, it is used to sort the chords by their combined flow, affecting only the z-order of the chords.

d3.chordDirected() for unidirectional flows

A chord layout for unidirectional flows. The chord from i to j is generated from the value in matrix[i][j] only.

chord.sortSubgroups(compare) method

If compare is specified, sets the subgroup comparator to the specified function or null and returns the chord layout. If compare is not specified, returns the current subgroup comparator, which defaults to null. If the subgroup comparator is non-null, it is used to sort the subgroups corresponding to matrix[i][0 … n - 1] for a given group i by their total outflow.

d3.chordTranspose() for outgoing flows

A transposed chord layout useful to highlight outgoing (rather than incoming) flows.

d3.chord() constructor

Constructs a new chord layout with default settings. Call d3.chord() to create a chord layout instance.

chord(matrix) input and output format

Computes the chord layout for a square n×n matrix representing directed flow among n nodes. Returns an array of chord objects, where each chord has a source and target subgroup. Each subgroup has startAngle (radians), endAngle (radians), value (flow value), and index (node index). The returned array includes only chords where matrix[i][j] or matrix[j][i] is non-zero, and contains only unique chords (chord ij does not duplicate chord ji). The source is chosen such that it always represents the larger of matrix[i][j] and matrix[j][i].

chord().groups structure

The chords array also defines a secondary array chords.groups of length n, where each group represents the combined outflow for node i. Each group is an object with startAngle (radians), endAngle (radians), value (total outgoing flow for node i), and index (node index i).

chord.padAngle(angle) method

If angle is specified, sets the pad angle between adjacent groups to the specified number in radians and returns the chord layout. If angle is not specified, returns the current pad angle, which defaults to zero.

d3-chord module overview

d3-chord provides chord diagrams and ribbon shapes for visualizing relationships. It includes chord layout (with variants chordDirected and chordTranspose), ribbon shape generator, and ribbonArrow variant with configuration methods for padding angles, sorting, and accessors.

ribbon() creates a new ribbon generator

The d3.ribbon() function creates a new ribbon generator with default settings. It is used to generate SVG path data or render to a canvas context to represent bidirectional flow between two nodes in a chord diagram.

ribbon generator invocation with chord object

A ribbon generator is invoked by calling it with a chord object containing source and target properties. Each of source and target must have startAngle, endAngle, and radius properties. The generator returns a path data string or renders to a canvas context if one is set. For example: ribbon({source: {startAngle: 0.7524114, endAngle: 1.1212972, radius: 240}, target: {startAngle: 1.8617078, endAngle: 1.9842927, radius: 240}}) returns a path data string.

ribbon.source(source) accessor

Sets or gets the source accessor function. If source is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function source(d) { return d.source; }

ribbon.target(target) accessor

Sets or gets the target accessor function. If target is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function target(d) { return d.target; }

ribbon.sourceRadius(radius) accessor

Sets or gets the source radius accessor function. If radius is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function radius(d) { return d.radius; }

ribbon.targetRadius(radius) accessor

Sets or gets the target radius accessor function. If radius is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function radius(d) { return d.radius; } In asymmetric chord diagrams, the target radius is typically inset from the source radius to create a gap between the directed link and its associated group arc.

ribbon.endAngle(angle) accessor

Sets or gets the end angle accessor function. If angle is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function endAngle(d) { return d.endAngle; } The angle is specified in radians, with 0 at -y (12 o'clock) and positive angles proceeding clockwise.

ribbon.padAngle(angle) accessor

Sets or gets the pad angle accessor function. If angle is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function padAngle() { return 0; } The pad angle specifies the angular gap between adjacent ribbons.

ribbon.context(context) renders to canvas

Sets or gets the context for rendering. If context is specified (e.g., a canvas 2D context), sets it and returns the ribbon generator for chaining. If not specified, returns the current context, which defaults to null. When context is not null, the ribbon is rendered as a sequence of canvas path method calls. Otherwise, a path data string is returned representing the SVG path. See d3-path documentation.

ribbonArrow() creates an arrow ribbon generator

The d3.ribbonArrow() function creates a new arrow ribbon generator with default settings. This is suitable for use with chordDirected to represent unidirectional flow between nodes in a directed chord diagram.

ribbonArrow.headRadius(radius) accessor

Sets or gets the arrowhead radius accessor function. If radius is specified, sets the accessor and returns the ribbon generator for chaining. If not specified, returns the current accessor, which defaults to: function headRadius() { return 10; }

ribbon vs ribbonArrow purposes

Ribbon represents bidirectional flow between two nodes in a chord diagram. RibbonArrow represents unidirectional flow and is suitable for use with chordDirected in directed chord diagrams.

Give your agent this brain