Python3 pyplot module to generate hierarchical pie plots, i.e. "multi-level" pie plots of hierarchical data (as e.g. in disk usage diagrams).
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc
examples
hooks
hpie
.gitignore
.travis.yml
LICENSE.txt
README.rst
requirements.txt
setup.py

README.rst

Hierarchical Pie Charts Build Status Documentation Status

| Introduction | Features | Installation | Minimal Example | License |

Check out the full documentation at readthedocs.io.

Introduction

HPie is a module to create "Ring charts" or "Hierarchical Pie Charts" (also called "Multilevel Pie Charts" or "Sunburst Charts") together with the matplotlib package. Quoting Wikipedia:

A ring chart, also known as a sunburst chart or a multilevel pie chart, is used to visualize hierarchical data, depicted by concentric circles. The circle in the centre represents the root node, with the hierarchy moving outward from the center. A segment of the inner circle bears a hierarchical relationship to those segments of the outer circle which lie within the angular sweep of the parent segment.

A prominent example are disk usage charts (see examples/disk_usage_plot.py for this example):

Hpie Example: Disk Usage Chart

Features

HPie tries to be

  • Intuitive & Easy to use: After setting up your data and matplotlib, not more than two lines are nescessary to generate first plots (minimal example).
  • Flexible & Robust: Wherever it makes sense, the methods of the HPie class are intended to be overwritten. Methods that are resposible for spacing, coloring, styling etc. of the wedges take the corresponding data point (path) as an argument, allowing to set most properties independently for each wedge.

More specifically:

  • Clever positioning of labels, which - depending on space constraints are positioned in a tangentially or radially.
  • An easy way to "explode" the plot by redifining HPie.wedge_spacing (example, example).

Installation

As this project is still in development, you have to first have to clone the repository before installing the package with pip3:

git clone https://github.com/klieret/pyplot-hierarchical-pie

Alternatively click here to download the current state of the master branch. Change to the downloaded directory. To check that everything will work properly on your system, run:

python3 -m unittest discover

To install, run

sudo pip3 install .

All of the examples from the toplevel of examples/ will be run as well, so you can check examples/figures for the rendered graphics.

To uninstall, run

sudo pip3 uninstall hpie

To check if this package is installed, run

pip3 freeze | grep hpie

Minimal example

You can find several examples at examples/. Remember to either install this package or update your PYTHONPATH via (linux)

source setup_path.py

before running the examples. The most basic example is minimal_example_hpie.py:

import matplotlib.pyplot as plt
from hpie import HPie, stringvalues_to_pv

fig, ax = plt.subplots()

# set up some random data

data = stringvalues_to_pv({
    'ipsum':                      40.45,
    'ipsum/eirmod':               29.34,
    'ipsum/eirmod/dolor':         94.4,
    'lorem':                      36.12,
    'lorem/sadipscing/dolor':     44.32,
    'lorem/sadipscing/lorem':     37.15,
    'lorem/sadipscing/nonumy':    23.98,
    'lorem/eirmod':               11.12,
    'lorem/eirmod/lorem':         45.65,
    'lorem/sadipscing':           79.67,
})


# do the magic

hp = HPie(data, ax)

# set plot attributes

hp.plot(setup_axes=True)
ax.set_title('Example HPie')

# save/show plot

plt.show()

Running this script with python3 minimal_example_hpie.py will produce the following plot:

Screenshot Minimal Example

The Data

Note that the value corresponding to path is always the value excluding the values of the children of the path. Therefore plotting the HPie object computes a "completed" version of the "pathvalue dictionary". You can check this with the HPie._completed_pv instance variable which gets initialized after calling HPie.plot(*args). Running our minimal example prints the following:

hp._completed_pv.items() = {
    Path((, )): 442.2,  # = the total sum of all items =
                        # = 36.12 + 44.32 + 37.15 + 23.98 + ...
    Path(('ipsum', )): 164.19000000000003,  # = sum of "ipsum" and all of its children =
                                            # = 40.45 + 29.34 + 94.4
    Path(('ipsum', 'eirmod', )): 123.74000000000001, # = sum of ipsum/eirmod and all of its children =
                                                     # = 29.34 + 94.4
    Path(('ipsum', 'eirmod', 'dolor', )): 94.4,
    Path(('lorem', )): 278.01,
    Path(('lorem', 'eirmod', )): 56.769999999999996,
    Path(('lorem', 'eirmod', 'lorem', )): 45.65,
    Path(('lorem', 'sadipscing', )): 185.12,
    Path(('lorem', 'sadipscing', 'dolor', )): 44.32,
    Path(('lorem', 'sadipscing', 'lorem', )): 37.15,
    Path(('lorem', 'sadipscing', 'nonumy', )): 23.98,
}

hpie/tests/test_calc.py contains an explicit test of this calculation based on a similar example.

Ring Charts

Thus you get ring charts, if and only if all of the non-zero values correspond to paths with the same length. E.g. if we change the above data as follows (by lengthening the paths with question marks and removing the entry for the empty path):

data = stringvalues_to_pv({
    'ipsum/?/?':                 40.45,
    'ipsum/eirmod/?':            29.34,
    'ipsum/eirmod/dolor':        94.4,
    'lorem/?/?':                 36.12,
    'lorem/sadipscing/dolor':    44.32,
    'lorem/sadipscing/lorem':    37.15,
    'lorem/sadipscing/nonumy':   23.98,
    'lorem/eirmod/?':            11.12,
    'lorem/eirmod/lorem':        45.65,
    'lorem/sadipscing/?':        79.67,
})

we should get a classical ring chart. This is minimal_example_rings.py . Running it via python3 minimal_example_rings.py yields the following plot, which indeed just fills up the white space of the above plot with wedges labeled ?.

Minimal Example Rings

License

This project is licensed under the BSD 3-Clause License, see LICENSE.txt.