Repository files navigation

byRick Lupton andContributors

Many kinds of data can be thought of as 'flows': energy and materials movingthrough industry, money flowing through the economy, telephone lines movingbetween providers, voters moving between parties.floWeaver helps you toexchange and analyse flow data and visualise it usingSankey diagrams.

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

With floWeaver you canvisualise this as a variety ofSankey diagramsdepending on what you want to show:

Although there are a variety of tools for working with flow data and Sankeydiagrams in particular contexts, there are no open data formats for sharing databetween tools and domains. We aim to provide acommon data format and data convertersto support interoperability and open data.

You are free to copy, modify, and distribute floWeaver with attributionunder the terms of the MIT license. See theLICENSE filefor details. If you find it useful please acknowledge that by citing floWeaver(see below).

floWeaver is a Python package, but you can successfully use it as a data analysistool even without too much familiarity with Python. The best way to get started isto use it in aJupyter notebook (more advanced users canuse it outside the notebook environment to export JSON/SVG but this is stillunder development; seethis comment).

🚀Try floWeaver online with no installation:Quickstart tutorial on Binder.

To install floWeaver locally, you need Python 3 installed (you might want to install itusingAnaconda or Miniconda); see theinstallation page for full details.

You can install floweaver using conda:

conda install -c conda-forge floweaver

You likely also wantipysankeywidget to show Sankeydiagrams in the Jupyter notebook. Install it using conda:

conda install -c conda-forge ipysankeywidget

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

Alternatively, you can install floweaver using pip:

pip install floweaver

You likely also wantipysankeywidget to show Sankeydiagrams in the Jupyter notebook. Install this using pip and enable:

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

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

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

To get started, open thequickstart tutorial inJupyter notebook and step through the notebook cells to produce the fruit example shown above.

Tutorials, cookbook examples, and API documentation are all available on ReadTheDocs

If you have a question that isn't answered pleaseopen an issue on GitHub, if there isn't one there already. You canalso use theGitter chatroom for discussion and questions.

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, examplesof things that are more difficult than they should be or don't work, as well as actual fixes tocode and documentation. To get started seeCONTRIBUTING.md and ourcode ofconduct.

We have adetailed Roadmap showing what weare working on up to May 2018; beyond that there is thelonger-term Roadmap. We also havegood first issues grouped by type of contribution.

floWeaver builds on the approach described in the paperHybrid Sankey diagrams:Visual analysis of multidimensional data for understanding resource use. It usesipysankeywidget andd3-sankey-diagram for actually drawing the Sankeydiagrams.

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

R. C. Lupton and J. M. Allwood, ‘Hybrid Sankey diagrams: Visual analysis of multidimensionaldata 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 canget a citation of the latest version from Zenodo.

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