Sugikey

Description

This package aims at providing a reasonably simple and flexible way to draw Sankey diagrams and related flow diagrams in Python. Sankey diagrams are flow diagrams composed of arrows of width proportional to the flow of e.g. energy or mass. We use the Sugiyama method to derive layered graph layouts, hence the portmanteau Sugi(yama)(San)key.

Some key facts:

• Consumes pandas dataframes or networkx directed graphs as inputs.
• Uses NetworkX for processing of the underlying graph structure.
• Produces visual output with Matplotlib.
• Limitation: the created diagrams are not interactive, i.e. the arrows cannot be moved. Interactive Sankey diagrams can be created with a variety of other tools, including d3-Sankey.

Have a look at the documentation for more information.

Visuals

Installation

The simplest way to use Sugikey is to install the pypi package: pip install sugikey.

You can also use the Python code from the repository, provided you have installed the required packages. We use Poetry for dependency management.

You will need Python >= 3.10, as well as NetworkX, pandas, Matplotlib and PuLP for layout methods using mathematical optimization. The dependencies are managed with Poetry, which you can use to install the package (see poetry.lock and pyproject.toml).

Usage

The simplest way to use the package are the high-level functions sankey_from_dig and sankey_from_df, which take as input a networkx directed graph and a pandas dataframe, respectively.

import pandas as pd
from sugikey import sankey

# Sankey diagram from a pandas dataframe
flow_df = pd.read_csv(csv_path)
sankey.sankey_from_df(flow_df)

from sugikey import sankey

# Sankey diagram from a networkx directed graph
dig = examples.balanced_tree_with_cross_edge()
sankey.sankey_from_dig(dig)

Have a look at the documentation for more information.

More on Sankey diagrams

• Why Sankey diagrams are so great for understanding energy data

• Sankey diagrams now have the package they deserve

Support

Write an issue if there is an issue.

Authors and acknowledgment

Zlatan B.

Project status

This is a personal project without any guarantee.