DOCSEARCHbyAlgolia
Submit Docs

PyWaffle

repository·master·Indexed 20 days ago

https://github.com/gyli/pywaffle

A Python package for creating waffle charts, implemented as a specialized Figure class for Matplotlib. It enables visualization of proportions using blocks and Font Awesome icons, supporting customizable layouts, qualitative colormaps, and the ability to create multiple waffle plots within a single figure.

Tokens
10.4K
Snippets
39
Records
42
Agent score
70%

What's inside pywaffle

  1. Overview of PyWaffle

    master
    PyWaffle is an open-source, MIT-licensed Python package designed for creating waffle charts. It integrates with Matplotlib by providing a custom Waffle Figure constructor class. This class can be passed directly to matplotlib.pyplot.figure() to generate a Matplotlib Figure object specifically configured for waffle chart plotting.

  2. Use the Waffle Figure constructor with Matplotlib

    master

    To create a waffle chart, you use the Waffle class as the figure= argument in matplotlib.pyplot.figure(). This allows you to leverage the standard Matplotlib API while using PyWaffle's specialized layout logic.

    import matplotlib.pyplot as plt
from pywaffle import Waffle

# Pass the Waffle class to the figure function
fig = plt.figure(FigureClass=Waffle, **kwargs)

  3. Configure icons and legend styles

    master

    You can customize how icons appear in both the chart and the legend using the following parameters:

    • icons: A single icon name or a list/tuple of icon names (must match the length of values).
    • icon_style: Specifies the Font Awesome style (e.g., 'solid', 'regular', or 'brands'). Defaults to 'solid'. This can also be a list/tuple of styles to match the icons list.
    • icon_legend: Set to True to use the icons as symbols in the legend. If False, the legend will use standard color bars.
    • legend: A dictionary used to configure legend properties (e.g., labels, loc, bbox_to_anchor).
    # Example: Different icons and using icons in the legend
fig = plt.figure(
    FigureClass=Waffle,
    rows=5,
    values=[30, 16, 4],
    colors=["#FFA500", "#4384FF", "#C0C0C0"],
    icons=['sun', 'cloud-showers-heavy', 'snowflake'],
    font_size=20,
    icon_style='solid',
    icon_legend=True,
    legend={
        'labels': ['Sun', 'Shower', 'Snow'], 
        'loc': 'upper left', 
        'bbox_to_anchor': (1, 1)
    }
)

  4. Use pandas.Series for waffle chart values

    master

    The values parameter in PyWaffle accepts pandas.Series objects. This is useful for passing specific columns from a DataFrame.

    Note on Auto-labeling: Unlike when using a dictionary, passing a pandas.Series to values does not currently support automatic labeling. You must provide the labels parameter explicitly if you want labels for your data.

    # Example of passing a Series
# Note: auto-labeling is not supported for Series
'values': data['Factory A'] / 1000,
'labels': [f"{k} ({v})" for k, v in data['Factory A'].items()]

  5. How the Waffle FigureClass works

    master

    PyWaffle provides a Waffle class that acts as a matplotlib Figure constructor. Instead of calling plt.subplots(), you pass FigureClass=Waffle to plt.figure(). This allows you to define waffle-specific parameters like rows, columns, and values directly within the standard Matplotlib figure initialization.

    Key Concepts:

    • Value Scaling: If the sum of your values does not match the total number of blocks (rows * columns), PyWaffle automatically scales the values to fit the grid.
    • Auto-sizing: If you specify rows but not columns (or vice versa), PyWaffle uses the absolute values in values as the block numbers to determine the grid size.
    • Dictionary Input: If values is a dictionary, the keys are automatically used as labels in the legend.
    import matplotlib.pyplot as plt
from pywaffle import Waffle

fig = plt.figure(
    FigureClass=Waffle, 
    rows=5, 
    columns=10, 
    values=[48, 46, 6],
    figsize=(5, 3)
)
plt.show()

  6. Configure labels and legends in PyWaffle

    master

    PyWaffle provides two ways to handle labels:

    1. Using the labels parameter: Pass a list of strings. If this parameter is omitted, the keys from the values dictionary are used as labels by default.
    2. Using the legend parameter: Pass a dictionary containing arguments compatible with matplotlib.pyplot.legend. You can specify labels directly within the legend configuration using the labels key inside the dictionary.

    This is useful for creating custom formatted labels (e.g., including percentages) or placing labels in a legend box instead of directly on the chart.

    data = {'Cat1': 30, 'Cat2': 16, 'Cat3': 4}
fig = plt.figure(
    FigureClass=Waffle,
    rows=5,
    columns=10,
    values=data,
    # Option 1: Using labels parameter
    labels=[f"{k} ({int(v / sum(data.values()) * 100)}%)" for k, v in data.items()],
    # Option 2: Using legend parameter
    legend={
        'loc': 'lower left',
        'bbox_to_anchor': (0, -0.4),
        'ncol': len(data),
        'framealpha': 0,
        'fontsize': 12
    }
)

  7. Use the Waffle class to generate matplotlib figures

    master

    PyWaffle provides a Waffle figure constructor class. This class is designed to be passed directly to matplotlib.pyplot.figure, allowing you to generate a matplotlib Figure object specifically configured for waffle charts.

    import matplotlib.pyplot as plt
from pywaffle import Waffle

# Pass the Waffle class to plt.figure to create a waffle chart figure
fig = plt.figure(Figure=Waffle, rows=10, columns=10)
plt.show()

  9. Enable auto-sizing for rows or columns

    master

    To prevent values from being scaled and instead use the absolute numbers provided in values as the exact block counts, you can use auto-sizing.

    To enable this, provide an integer to only one of the rows or columns parameters and leave the other empty. PyWaffle will use the provided dimension and automatically calculate the other dimension to accommodate the total sum of values.

    # This will set rows to 5 and automatically calculate columns to fit the 97 total blocks
plt.figure(
    FigureClass=Waffle,
    rows=5,
    values=[48, 46, 3]
)

  10. Customize figure properties like size, DPI, and background color

    master

    You can pass standard matplotlib.pyplot.figure parameters directly to the Waffle class by using the FigureClass argument. This allows you to control properties such as figsize, dpi, facecolor, and more. To change the background color of the figure, pass a color value to the facecolor parameter.

    fig = plt.figure(
    FigureClass=Waffle,
    rows=5,
    values=[30, 16, 4],
    colors=["#232066", "#983D3D", "#DCB732"],
    facecolor='#DDDDDD'  # facecolor is a parameter of matplotlib.pyplot.figure
)

  12. Change the plot location using plot_anchor

    master

    Use the plot_anchor parameter to adjust the position of the waffle plot within the figure. For example, setting plot_anchor='S' will anchor the plot to the South (bottom) of the figure area.

    fig = plt.figure(
    FigureClass=Waffle,
    rows=5,
    values=[30, 16, 4],
    plot_anchor='S'
)
fig.set_facecolor('#DDDDDD')