Chord diagrams

A chord diagram is a graphical method of displaying the inter-relationships between data in a matrix. The data are arranged radially around a circle with the relationships between the data points typically drawn as arcs connecting the data. Wikipedia

Chord diagrams accept the standard parameter plus an optional labels argument as described below.

Data

Data is provided as follows:

• The links ("chords") between groups
• Optionally, the labels of each group (If the labels are omitted, the nodes are labeled "Group 1", "Group 2" and so on.)

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 i^th node to the j^th 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.)

Data can be provided either in-line, as per all other charts, or from a file.

Examples

The following are all valid and all produce the following chart, the data for which was derived from a demo dataset on Circos:

• Separate chords and labels, inline:

<chord
  data='[
    [11975,  5871, 8916, 2868],
    [ 1951, 10048, 2060, 6171],
    [ 8010, 16145, 8090, 8045],
    [ 1013,   990,  940, 6907]
  ]'
  labels='["black", "blond", "brunette", "redhead"]'
  colors='["black", "#ffdd89", "#957244", "#f26223"]'>
</chord>

• Or from a file (e.g. example.json) that contains:

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

<chord
  path='example.json'
  labels='["black", "blond", "brunette", "redhead"]'
  colors='["black", "#ffdd89", "#957244", "#f26223"]'>
</chord>

• Single dictionary argument with both chords and labels:

<chord
  data='{
    "chords": [
      [11975,  5871, 8916, 2868],
      [ 1951, 10048, 2060, 6171],
      [ 8010, 16145, 8090, 8045],
      [ 1013,   990,  940, 6907]
    ],
    "labels": [
      "black", "blond", "brunette", "redhead"
    ]
  }'
  colors='["black", "#ffdd89", "#957244", "#f26223"]'>
</chord>

• Single dictionary argument with chords only and labels included separately

<chord
  data='{
    "chords": [
      [11975,  5871, 8916, 2868],
      [ 1951, 10048, 2060, 6171],
      [ 8010, 16145, 8090, 8045],
      [ 1013,   990,  940, 6907]
    ]
  }'
  colors='["black", "#ffdd89", "#957244", "#f26223"]'
  labels='["black", "blond", "brunette", "redhead"]'>
</chord>

• Data and labels from a DataFrame (Python only)

import doodl
import pandas as pd

df = pd.DataFrame(
  [
      [11975,  5871, 8916, 2868],
      [ 1951, 10048, 2060, 6171],
      [ 8010, 16145, 8090, 8045],
      [ 1013,   990,  940, 6907]
  ],
  columns=[
    "black", "blond", "brunette", "redhead"
  ]
)

doodl.chord(
  data=df,
  colors=["black", "#ffdd89", "#957244", "#f26223"]
)