Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Hierarchical Pie Charts Build Status Documentation Status

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

Check out the full documentation at


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/ for this example):

Hpie Example: Disk Usage Chart


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).


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

git clone

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)


before running the examples. The most basic example is

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

ax.set_title('Example HPie')

# save/show plot

Running this script with python3 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/ 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 . Running it via python3 yields the following plot, which indeed just fills up the white space of the above plot with wedges labeled ?.

Minimal Example Rings


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


Python3 pyplot module to generate hierarchical pie plots, i.e. "multi-level" pie plots of hierarchical data (as e.g. in disk usage diagrams).





No releases published


No packages published