Python package for creating beautiful interactive Chord Diagrams.
Project description
Chord PRO Released
Chord PRO is the full-featured chord visualization API, producing beautiful interactive visualizations, e.g. those featured on the front page of Reddit.
- Produce beautiful interactive Chord diagrams.
- Customize colours and font-sizes.
- Access Divided mode, enabling two sides to your diagram.
- Add images and text on hover,
- Access finer-customisations including HTML injection.
- Allows commercial use without open source requirement.
- Currently supports Python, JavaScript, and Rust, with many more to come (accepting requests).
Changelog:
-
23 July 2020 -
Chord PRO
now supports figure titles. -
20 July 2020 -
Chord PRO
now supports asymmetric mode usingsymmetric=False
! You can also overide theverb
used in the popup. -
14 July 2020 -
Chord PRO
can now be enabled by entering your license key. -
29 June 2020 - Optimisation and bug fixes to the tooltip have massively improved the interactive performance of the visualisation (Rebuild your chord diagrams to take advantage of this change).
-
22 May 2020 - Optimisation and bug fixes have massively improved the interactive performance of the visualisation (Rebuild your chord diagrams to take advantage of this change).
-
21 May 2020 - Please update to the latest version of
chord
. Backwards compatability has been introduced, so from this version onwards, new versions won't break older ones!
Introduction
In a chord diagram (or radial network), entities are arranged radially as segments with their relationships visualised by arcs that connect them. The size of the segments illustrates the numerical proportions, whilst the size of the arc illustrates the significance of the relationships1.
Chord diagrams are useful when trying to convey relationships between different entities, and they can be beautiful and eye-catching.
The Chord Package
I wanted to do a section on Chord Diagrams for my book, Data Is Beautiful.
With Python in mind, there are many libraries available for creating Chord diagrams, such as Plotly, Bokeh, and a few that are lesser-known. However, I wanted to use the implementation from d3 because it can be customised to be highly interactive and to look beautiful.
I couldn't find anything that ticked all the boxes, so I made a wrapper around d3-chord myself. It took some time to get it working, but I wanted to hide away everything behind a single constructor and method call. The tricky part was enabling multiple chord diagrams on the same page, and then loading resources in a way that would support Jupyter Lab.
The primary support is for Jupyter Lab
(not the older Jupyter Notebook
).
Installation
Available on https://pypi.org/project/chord/ through pip
:
pip install chord
Usage
Python
Python (HTML file)
Chord(matrix, names).to_html()
Jupyter Lab (Notebook)
Chord(matrix, names).show()
Defaults
Chord(self,
matrix,
names,
colors="d3.schemeSet1",
opacity=0.8,
padding=0.01,
width=700,
label_color="#454545",
wrap_labels=True,
margin=0,
credit=False,
)
Examples
You can see the actual interactive examples on this page. The below examples are screenshots.
The Dataset
The focus for this section will be the demonstration of the chord
package. To keep it simple, we will use synthetic data that illustrates the co-occurrences between movie genres within the same movie.
matrix = [
[0, 5, 6, 4, 7, 4],
[5, 0, 5, 4, 6, 5],
[6, 5, 0, 4, 5, 5],
[4, 4, 4, 0, 5, 5],
[7, 6, 5, 5, 0, 4],
[4, 5, 5, 5, 4, 0],
]
names = ["Action", "Adventure", "Comedy", "Drama", "Fantasy", "Thriller"]
Default Settings
Let's see what the Chord()
defaults produce when we invoke the show()
method.
Chord(matrix, names).show()
You can also save it to a HTML file.
Chord(matrix, names).to_html()
Different Colours
The defaults are nice, but what if we want different colours? You can pass in almost anything from d3-scale-chromatic, or you could pass in a list of hexadecimal colour codes.
Chord(matrix, names, colors="d3.schemeSet2").show()
Chord(matrix, names, colors=f"d3.schemeGnBu[{len(names)}]").show()
Chord(matrix, names, colors="d3.schemeSet3").show()
Chord(matrix, names, colors=f"d3.schemePuRd[{len(names)}]").show()
Chord(matrix, names, colors=f"d3.schemeYlGnBu[{len(names)}]").show()
hex_colours = ["#222222", "#333333", "#4c4c4c", "#666666", "#848484", "#9a9a9a"]
Chord(matrix, names, colors=hex_colours).show()
Label Styling
We can disable the wrapped labels, and even change the colour.
Chord(matrix, names, wrap_labels=False, label_color="#4c40bf").show()
Opacity
We can also change the default opacity of the relationships.
Chord(matrix, names, opacity=0.1).show()
Diagram Size
We can change the maximum diagram size by specifying a width.
Chord(matrix, names, width=400).show()
We can change the padding between chord segments by specifying the padding.
Chord(matrix, names, padding=0.3).show()
-
Tintarev, N., Rostami, S., & Smyth, B. (2018, April). Knowing the unknown: visualising consumption blind-spots in recommender systems. In Proceedings of the 33rd Annual ACM Symposium on Applied Computing (pp. 1396-1399). ↩
Credits
- d3-chord, Mike Bostock.
- d3-chord gradient fills, Nadieh Bremer.
chord
(Python), Shahin Rostami.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.