Setting the Title

Preamble

In [1]:
from plotapi import Chord

Chord.set_license("your username", "your license key")

Introduction

Plotapi Chord allows setting a title for the diagram by passing in a string.

As we can see, we have set our license details in the preamble with Chord.set_license()

Dataset

Chord expects a list of names (list[str]) and a co-occurence matrix (list[list[float]]) as input.

In [2]:
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"]

It may look more clear if we present this as a table with the columns and indices labelled. This is entirely optional.

In [3]:
import pandas as pd
pd.DataFrame(matrix, columns=names, index=names)
Out[3]:
Action Adventure Comedy Drama Fantasy Thriller
Action 0 5 6 4 7 4
Adventure 5 0 5 4 6 5
Comedy 6 5 0 4 5 5
Drama 4 4 4 0 5 5
Fantasy 7 6 5 5 0 4
Thriller 4 5 5 5 4 0

Visualisation

To include a diagram title, we can pass the desired string into the title parameter.

Be sure to interact with the visualisation to see what the default settings can do!

In [4]:
Chord(matrix, names, title="Movie Genre Co-occurrence").show()
Plotapi - Chord Diagram

You can do so much more than what's presented in this example, and we'll cover this in later sections. If you want to see the full list of growing features, check out the Plotapi Documentation. and the Plotapi Gallery.

Numbering the Outer Arc

Preamble

In [1]:
from plotapi import Chord

Chord.set_license("your username", "your license key")

Introduction

Depending on our data, displaying the quantity associated with each segment as a label may be useful.

As we can see, we have set our license details in the preamble with Chord.set_license()

Dataset

Chord expects a list of names (list[str]) and a co-occurence matrix (list[list[float]]) as input.

In [2]:
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"]

It may look more clear if we present this as a table with the columns and indices labelled. This is entirely optional.

In [3]:
import pandas as pd
pd.DataFrame(matrix, columns=names, index=names)
Out[3]:
Action Adventure Comedy Drama Fantasy Thriller
Action 0 5 6 4 7 4
Adventure 5 0 5 4 6 5
Comedy 6 5 0 4 5 5
Drama 4 4 4 0 5 5
Fantasy 7 6 5 5 0 4
Thriller 4 5 5 5 4 0

Visualisation

The visibility of quantity labels can be controlled with the arc_numbers parameter. Setting it to True will enable them.

Be sure to interact with the visualisation to see what the default settings can do!

In [4]:
Chord(matrix, names, arc_numbers=True).show()
Plotapi - Chord Diagram

You can do so much more than what's presented in this example, and we'll cover this in later sections. If you want to see the full list of growing features, check out the Plotapi Documentation. and the Plotapi Gallery.

Reversed Ribbon Gradients

Preamble

In [1]:
from plotapi import Chord

Chord.set_license("your username", "your license key")

Introduction

Depending on our data, it may make more sense to reverse the gradient directions used for colouring the ribbons.

As we can see, we have set our license details in the preamble with Chord.set_license()

Dataset

Chord expects a list of names (list[str]) and a co-occurence matrix (list[list[float]]) as input.

In [2]:
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"]

It may look more clear if we present this as a table with the columns and indices labelled. This is entirely optional.

In [3]:
import pandas as pd
pd.DataFrame(matrix, columns=names, index=names)
Out[3]:
Action Adventure Comedy Drama Fantasy Thriller
Action 0 5 6 4 7 4
Adventure 5 0 5 4 6 5
Comedy 6 5 0 4 5 5
Drama 4 4 4 0 5 5
Fantasy 7 6 5 5 0 4
Thriller 4 5 5 5 4 0

Visualisation

The gradient directions can be controlled with the reverse_gradients parameter. Setting it to True will reverse them.

Be sure to interact with the visualisation to see what the default settings can do!

In [11]:
Chord(matrix, names, reverse_gradients=True).show()
Plotapi - Chord Diagram

You can do so much more than what's presented in this example, and we'll cover this in later sections. If you want to see the full list of growing features, check out the Plotapi Documentation. and the Plotapi Gallery.

Adjusting Layout Properties

Preamble

In [1]:
from plotapi import Terminus

Terminus.set_license("your username", "your license key")

Introduction

Let's take a look at some parameters that control the layout of our diagram.

As we can see, we have set our license details in the preamble with Terminus.set_license().

Dataset

Terminus expects a list of dictionary items, these will define the flow of pixels between a source and a target.

In [2]:
links = [
    {"source":"England", "target":"Germany", "value": 1000},
    {"source":"England", "target":"France", "value": 3000},
    {"source":"England", "target":"Spain", "value": 5000},
    {"source":"England", "target":"Italy", "value": 4000},
    {"source":"England", "target":"Japan", "value": 800},

    
    {"source":"Ireland", "target":"Germany", "value": 3500},
    {"source":"Ireland", "target":"France", "value": 3750},
    {"source":"Ireland", "target":"Spain", "value": 1750},
    {"source":"Ireland", "target":"Italy", "value": 5000},
    {"source":"Ireland", "target":"Japan", "value": 400},
]

We can add many source's and target's! As they increase, we may need to adjust Terminus layout properties to accomodate the diagram's size and throughput.

Visualisation

We can modify the width, height, and margin of our diagram.

The margin parameter can be a dictionary that defines the size of the top, _right, bottom, and left margins - or - it can also be a single float to imply an equal margin of that size.

By default a Terminus diagram is centered, but this can be disabled with center=False.

Here we're using .show() which outputs to a Jupyter Notebook cell, however, we may want to output to an HTML file with .to_html() instead. More on the different output methods later!

In [3]:
Terminus(links, width=800, height=500, margin=100).show()
Plotapi - Terminus Diagram

You can do so much more than what's presented in this example, and this is covered in other sections. If you want to see the full list of growing features, check out the Plotapi API Documentation.

Changing Ribbon Opacity

Preamble

In [1]:
from plotapi import Chord

Chord.set_license("your username", "your license key")

Introduction

We can change the opacity of the inner section of our Chord diagram, or the ribbons. The opacity will change on mouseover to highlight the selected connections.

As we can see, we have set our license details in the preamble with Chord.set_license()

Dataset

Chord expects a list of names (list[str]) and a co-occurence matrix (list[list[float]]) as input.

In [2]:
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"]

It may look more clear if we present this as a table with the columns and indices labelled. This is entirely optional.

In [3]:
import pandas as pd
pd.DataFrame(matrix, columns=names, index=names)
Out[3]:
Action Adventure Comedy Drama Fantasy Thriller
Action 0 5 6 4 7 4
Adventure 5 0 5 4 6 5
Comedy 6 5 0 4 5 5
Drama 4 4 4 0 5 5
Fantasy 7 6 5 5 0 4
Thriller 4 5 5 5 4 0

Visualisation

The opacity parameter controls the ribbon opacity for Chord. This value must be a float between or equal to $0.0$ and $1.0$.

Be sure to interact with the visualisation to see what the default settings can do!

In [4]:
Chord(matrix, names, opacity=0.2).show()
Plotapi - Chord Diagram

You can do so much more than what's presented in this example, and we'll cover this in later sections. If you want to see the full list of growing features, check out the Plotapi Documentation. and the Plotapi Gallery.

Bundled Pipes for Grouping

Preamble

In [1]:
from plotapi import Terminus

Terminus.set_license("your username", "your license key")

Introduction

Let's take a look at the bundled parameter. This will group together the input, giving the impression that they are entering through the same pipe.

As we can see, we have set our license details in the preamble with Terminus.set_license().

Dataset

Terminus expects a list of dictionary items, these will define the flow of pixels between a source and a target.

In [2]:
links = [
    {"source":"England", "target":"Germany", "value": 1000},
    {"source":"England", "target":"France", "value": 3000},
    {"source":"England", "target":"Spain", "value": 5000},
    {"source":"England", "target":"Italy", "value": 4000},
    {"source":"England", "target":"Japan", "value": 800},

    
    {"source":"Ireland", "target":"Germany", "value": 3500},
    {"source":"Ireland", "target":"France", "value": 3750},
    {"source":"Ireland", "target":"Spain", "value": 1750},
    {"source":"Ireland", "target":"Italy", "value": 5000},
    {"source":"Ireland", "target":"Japan", "value": 400},
]

We can add many source's and target's! As they increase, we may need to adjust Terminus layout properties to accomodate the diagram's size and throughput.

Visualisation

To enable bundled pipes, all we need to do is set bundled to True.

Here we're using .show() which outputs to a Jupyter Notebook cell, however, we may want to output to a HTML file with .to_html() instead. More on the different output methods later!

In [5]:
Terminus(links, bundled=True).show()
Plotapi - Terminus Diagram

You can do so much more than what's presented in this example, and this is covered in other sections. If you want to see the full list of growing features, check out the Plotapi API Documentation.

Changing the Colours

Preamble

In [1]:
from plotapi import Chord

Chord.set_license("your username", "your license key")

Introduction

We can change our Chord diagram's colour scheme to one of many beautiful presets, or even supply our own list of colours as HEX colour codes.

As we can see, we have set our license details in the preamble with Chord.set_license()

Dataset

Chord expects a list of names (list[str]) and a co-occurence matrix (list[list[float]]) as input.

In [2]:
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"]

It may look more clear if we present this as a table with the columns and indices labelled. This is entirely optional.

In [3]:
import pandas as pd
pd.DataFrame(matrix, columns=names, index=names)
Out[3]:
Action Adventure Comedy Drama Fantasy Thriller
Action 0 5 6 4 7 4
Adventure 5 0 5 4 6 5
Comedy 6 5 0 4 5 5
Drama 4 4 4 0 5 5
Fantasy 7 6 5 5 0 4
Thriller 4 5 5 5 4 0

Visualisation

To specify colours, we can set the colors parameter to one of the following:

  • A list of colour strings, e.g. ["#264653","#2a9d8f","#e9c46a","#f4a261","#e76f51"]. If there are fewer colours than there are categories, Chord will loop round the colours.
  • The string name of a predefined set of colours from the following list: ['monsters', 'category10', 'accent', 'dark2', 'paired', 'pastel1', 'pastel2', 'set1', 'set2', 'set3', 'tableau10', 'rainbow', 'sinebow', 'yellow_red', 'yellow_brown', 'yellow_green', 'yellow_blue', 'red_purple', 'purple_red', 'purple_blue', 'orange_red', 'green_blue', 'blue_purple', 'blue_green', 'cubehelix', 'cool', 'warm', 'cividis', 'plasma', 'magma', 'inferno', 'viridis', 'turbo', 'brown_green', 'purple_green', 'pink_green', 'red_blue', 'red_grey', 'red_yellow_blue', 'red_yellow_green', 'spectral', 'blues', 'greens', 'greys', 'oranges', 'purples', 'reds'].

Here we're using .show() and show_png() which outputs to a Jupyter Notebook cell, however, we may want to output to a file with .to_html() or .to_png() instead. More on the different output methods later!

The default colour scheme is "rainbow". Let's try a few different colour schemes.

Be sure to interact with the visualisation to see what the default settings can do!

In [21]:
Chord(matrix, names, colors="plasma").show()
Plotapi - Chord Diagram
In [22]:
Chord(matrix, names, colors="monsters").show_png()
In [23]:
Chord(matrix, names, colors=["#333", "cyan", "magenta"]).show_png()