View flow data as Sankey diagrams

ricklupton, updated 🕥 2023-02-14 11:18:16

.. image:: docs/_static/logo.png :alt: floWeaver :align: center :width: 697 :height: 222 :target: https://github.com/ricklupton/floweaver

.. image:: https://badge.fury.io/py/floweaver.svg :target: https://badge.fury.io/py/floweaver :alt: PyPI Status .. image:: https://readthedocs.org/projects/floweaver/badge/?version=latest :target: http://floweaver.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. image:: https://travis-ci.org/ricklupton/floweaver.svg?branch=master :target: https://travis-ci.org/ricklupton/floweaver :alt: Test Status .. image:: https://codecov.io/gh/ricklupton/floweaver/branch/master/graph/badge.svg :target: https://codecov.io/gh/ricklupton/floweaver :alt: Coverage Status .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.161970.svg :target: https://doi.org/10.5281/zenodo.596249 :alt: DOI

by Rick Lupton <http://www.ricklupton.name> and Contributors

Many kinds of data can be thought of as 'flows': energy and materials moving through industry, money flowing through the economy, telephone lines moving between providers, voters moving between parties. floWeaver helps you to exchange and analyse flow data and visualise it using Sankey diagrams <https://en.wikipedia.org/wiki/Sankey_diagram>_.

For example, here is some data on flows of fruit from farms to customers:

.. image:: docs/demo_table.png

With floWeaver you can visualise this as a variety of Sankey diagrams depending on what you want to show:

.. image:: docs/demo_animation/demo.gif

Although there are a variety of tools for working with flow data and Sankey diagrams in particular contexts, there are no open data formats for sharing data between tools and domains. We aim to provide a common data format and data converters to support interoperability and open data.

You are free to copy, modify, and distribute floWeaver with attribution under the terms of the MIT license. See the LICENSE <LICENSE> file for details. If you find it useful please acknowledge that by citing floWeaver (see below <#citing-floweaver>).

Get started using floWeaver

floWeaver is a Python package, but you can successfully use it as a data analysis tool even without too much familiarity with Python. The best way to get started is to use it in a Jupyter notebook <http://jupyter.org/> (more advanced users can use it outside the notebook environment to export JSON/SVG but this is still under development; see this comment <https://github.com/ricklupton/floweaver/issues/34#issuecomment-385040059>).

🚀 Try floWeaver online with no installation: Quickstart tutorial on Binder <https://mybinder.org/v2/gh/ricklupton/floweaver/master?filepath=docs%2Ftutorials%2Fquickstart.ipynb>_.

To install floWeaver locally, you need Python 3 installed (you might want to install it using Anaconda or Miniconda <https://www.continuum.io/downloads>); see the installation page <https://floweaver.readthedocs.io/en/latest/installation.html> for full details.

Installation using conda

You can install floweaver using conda:

.. code-block:: console

conda install -c conda-forge floweaver

You likely also want ipysankeywidget <https://github.com/ricklupton/ipysankeywidget>_ to show Sankey diagrams in the Jupyter notebook. Install it using conda:

.. code-block:: console

conda install -c conda-forge ipysankeywidget

(that's it — the jupyter nbextensions are enabled automatically when using conda)

Installation using pip

Alternatively, you can install floweaver using pip:

.. code-block:: console

pip install floweaver

You likely also want ipysankeywidget <https://github.com/ricklupton/ipysankeywidget>_ to show Sankey diagrams in the Jupyter notebook. Install this using pip and enable:

.. code-block:: console

pip install ipysankeywidget jupyter nbextension enable --py --sys-prefix ipysankeywidget

ipywidgets also needs to be enabled. You might have already done this, but missing it out is a common cause of problems so it doesn't hurt to do it again!

.. code-block:: console

jupyter nbextension enable --py --sys-prefix widgetsnbextension

Quickstart tutorial

To get started, open the quickstart tutorial <docs/tutorials/quickstart.ipynb>_ in Jupyter notebook and step through the notebook cells to produce the fruit example shown above.

Find out more 📖

Tutorials, cookbook examples, and API documentation are all available on ReadTheDocs <https://floweaver.readthedocs.io/en/latest/>_

If you have a question that isn't answered please open an issue on GitHub <https://github.com/ricklupton/floweaver/issues>, if there isn't one there already. You can also use the Gitter chatroom <https://gitter.im/floweaver/Lobby> for discussion and questions.

Contributing 🎁

Thanks for your interest in contributing! There are many ways to contribute to floWeaver: sharing examples of work done using it, suggestions for improving the documentation, examples of things that are more difficult than they should be or don't work, as well as actual fixes to code and documentation. To get started see CONTRIBUTING.md <CONTRIBUTING.md> and our code of conduct <CODE_OF_CONDUCT.md>.

We have a detailed Roadmap <https://github.com/ricklupton/floweaver/projects/2> showing what we are working on up to May 2018; beyond that there is the longer-term Roadmap <https://github.com/ricklupton/floweaver/projects/1>. We also have good first issues grouped by type of contribution <https://github.com/ricklupton/floweaver/projects/3>_.

How does it work?

floWeaver builds on the approach described in the paper Hybrid Sankey diagrams: Visual analysis of multidimensional data for understanding resource use <https://doi.org/10.1016/j.resconrec.2017.05.002>. It uses ipysankeywidget <https://github.com/ricklupton/ipysankeywidget> and d3-sankey-diagram <https://github.com/ricklupton/d3-sankey-diagram>_ for actually drawing the Sankey diagrams.

.. image:: docs/project_components.png

Citing floWeaver

If floweaver has been significant in a project that leads to a publication, please acknowledge that by citing the paper linked above:

R. C. Lupton and J. M. Allwood, ‘Hybrid Sankey diagrams: Visual analysis of multidimensional data for understanding resource use’, Resources, Conservation and Recycling, vol. 124, pp. 141–151, Sep. 2017. DOI: 10.1016/j.resconrec.2017.05.002

and/or citing the software itself; you can get a citation of the latest version from Zenodo <https://doi.org/10.5281/zenodo.596249>_.

Contributors

Leo Paoli (documentation)
Konstantin Stadler (issues & use in IOA)
Dhanuka Lakshan
Andreas Fehlner
Elliott Sales de Andrade
@abmakko (the logo)
Chris Barnes (@clbarnes)

Issues

Bump certifi from 2020.4.5.1 to 2022.12.7

opened on 2022-12-08 10:23:05 by dependabot[bot]

Bumps certifi from 2020.4.5.1 to 2022.12.7.

Commits

9e9e840 2022.12.07
b81bdb2 2022.09.24
939a28f 2022.09.14
aca828a 2022.06.15.2
de0eae1 Only use importlib.resources's new files() / Traversable API on Python ≥3.11 ...
b8eb5e9 2022.06.15.1
47fb7ab Fix deprecation warning on Python 3.11 (#199)
b0b48e0 fixes #198 -- update link in license
9d514b4 2022.06.15
4151e88 Add py.typed to MANIFEST.in to package in sdist (#196)
Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) - `@dependabot use these labels` will set the current labels as the default for future PRs for this repo and language - `@dependabot use these reviewers` will set the current reviewers as the default for future PRs for this repo and language - `@dependabot use these assignees` will set the current assignees as the default for future PRs for this repo and language - `@dependabot use this milestone` will set the current milestone as the default for future PRs for this repo and language You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/ricklupton/floweaver/network/alerts).

Starting new flows from waypoints and preserving order

opened on 2022-10-09 22:06:10 by gsgoncalves

Hi,

Great project! I was wondering if I could adapt this framework for my use case.

I need new flows to start at waypoints and add them to the following waypoints so that each flow has a distinct waypoint level.

For example: Here Banana appears at level 2, passes through the second waypoint, and finishes with the other flows that begin at the start. Great!

flow-1-example

Question 1: Can I add this same functionality for an arbitrary number of flows that may start at any waypoint and continue until the end? Question 2: Moreover, the new flows such as "Banana" can start at any position, including between the original flows?

I have managed to produce the following 2 outputs, but they are not preserving a waypoint level for each flow, and I cannot make the new flow start between any of the original flows.

flow-2-example

flow-3-example

Code for generating example 1

Code for generating example 2

Code for generating example 3

Does anyone know how to do this, or if it is possible?

Question 3: Is it possible to add free text labels without breaking the flows?

Thank you!

Adjusting size of nodes

opened on 2022-09-08 11:56:51 by ccampbell-can

Hi,

Is there a way to adjust the size and colour of the nodes within floweaver? I am plotting the movement in voters between political parties and would like the nodes to be both thicker and coloured to represent the party colours? Many thanks for any guidance.

plotting multiple diagrams

opened on 2022-07-26 19:10:03 by JFA-CT

Hi there, Is there any way to plot two sankey diagrams in the same html? I'm trying to do a visual comparison so that the relative size of the lines are proportional (and thus both sankeys are comparable but still separate) to each other? Thanks for any tips.

Bump notebook from 6.0.3 to 6.4.12

opened on 2022-06-17 00:07:33 by dependabot[bot]

Bumps notebook from 6.0.3 to 6.4.12.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

Is it possible to control the positioning of the labels?

opened on 2022-05-17 14:33:19 by Fernando3161

Hi! Thanks for this wonderful tool!!!!! I am currently preparing some Sankeys and I would like to know if I can control the positioning of the labels of the nodes and of the groups: For example; I would like all of the Group Names to be placed BELOW the grey column, and all of the labels (expect for the nodes on the left) to be placed on the center-right of the node. Can I somehow control or set this up?

Regards, FP

Releases

v1.1.7 2017-11-03 19:16:09

First public release 2016-10-19 14:45:16

Rick Lupton

Lecturer at University of Bath

GitHub Repository Homepage

python jupyter data-visualization data-visualisation data-structures svg d3 sankey-diagram sankey flow