API Reference#

Function#

Plot a waffle chart.

Run it with code like:

fig, ax = waffle_chart([48, 46, 6], rows=5)

or draw into an axes you already have:

fig, axes = plt.subplots(1, 2)
waffle_chart({"Yes": 70, "No": 30}, rows=5, ax=axes[0])

This is a wrapper around the Waffle figure class. Every parameter behaves exactly as documented there; see Waffle for the full reference. The two matplotlib-native forms remain supported and are not deprecated:

plt.figure(FigureClass=Waffle, rows=5, values=[48, 46, 6])
Waffle.make_waffle(ax=ax, rows=5, values=[48, 46, 6])

Parameters:

values (list|dict|tuple|pandas.Series) – Numerical value of each category. If it is a dict, the keys are used as labels.
rows (int, optional) – The number of lines of the waffle chart.
columns (int, optional) –
The number of columns of the waffle chart.

At least one of rows and columns is required.
ax (matplotlib.axes.Axes, optional) –
Draw into this axes instead of creating a new figure.

When given, the axes’ figure is returned rather than a new one, and no figure-level arguments (such as figsize or dpi) are accepted.
**kwargs – Additional arguments passed to matplotlib.pyplot.figure(), such as figsize, dpi or facecolor. Only accepted when ax is not given.

Returns:

(figure, axes)

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

Figure class#

class pywaffle.waffle.Waffle(*args, **kwargs)#

A custom Figure class to make waffle charts.

Parameters:

values (list|dict|pandas.Series) –
Numerical value of each category.

If it is a dict, the keys are used as labels.

If it is a pandas Series, the index is used as labels.
rows (int) – The number of lines of the waffle chart.
columns (int) –
The number of columns of the waffle chart.

At least one of rows and columns is required.

If either rows or columns is passed, the other is calculated automatically from the sum of values.

If both of rows and columns are passed, the block number is fixed and block numbers are calculated from scaled values.
colors (list[str]|tuple[str], optional) –
A list of colors for each category. Its length should be the same as values.

Default values are from Set2 colormap.
labels (list[str]|tuple[str], optional) –
The name of each category.

If the values is a dict, this parameter would be replaced by the keys of values.
legend (dict, optional) –
Parameters of matplotlib.pyplot.legend in a dict.

E.g. {‘loc’: ‘’, ‘bbox_to_anchor’: (,), …}

See full parameter list in https://matplotlib.org/api/_as_gen/matplotlib.pyplot.legend.html
interval_ratio_x (float, optional) – Ratio of horizontal distance between blocks to block’s width. [Default 0.2]
interval_ratio_y (float, optional) – Ratio of vertical distance between blocks to block’s height. [Default 0.2]
block_aspect_ratio (float, optional) – The ratio of block’s width to height. [Default 1]
cmap_name (str, optional) –
Name of colormaps for default color, if colors is not assigned.

A qualitative colormap, such as the default ‘Set2’, is used in order and repeated if there are more categories than colors. Any other colormap is sampled evenly across its range, so that the categories are visibly distinct.

See full list in https://matplotlib.org/stable/users/explain/colors/colormaps.html

[Default ‘Set2’]
title (dict, optional) –
Parameters of matplotlib.axes.Axes.set_title in a dict.

E.g. {‘label’: ‘’, ‘fontdict’: {}, ‘loc’: ‘’}

See full parameter list in https://matplotlib.org/api/_as_gen/matplotlib.pyplot.title.html
characters – A character in string or a list of characters for each category. [Default None]
font_size –
Font size of Font Awesome icons.

The default size is not fixed and depends on the block size.

Either a relative value of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’ or ‘xx-large’, or an absolute font size.
font_file – Path to custom font file.
icons (str|list[str]|tuple[str], optional) –
Icon name of Font Awesome.

If it is a string, all categories use the same icon;

If it’s a list or tuple of icons, the length should be the same as values.

See the full list of Font Awesome on https://fontawesome.com/icons?d=gallery&m=free

[Default None]
icon_style (str|list[str]|tuple[str], optional) –
The style of icons to be used.

Font Awesome Icons find an icon by style and icon name. The style could be ‘brands’, ‘regular’ and ‘solid’. Visit https://fontawesome.com/cheatsheet for detail.

If it is a string, it would search icons within given style. If it is a list or a tuple, the length should be the same as values and it means the style for each icon.

[Default ‘solid’]
icon_size (int|str, optional) –
Font size of Font Awesome icons.

Deprecated! Use font_size instead.

The default size is not fixed and depends on the block size.

Either a relative value of ‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’ or ‘xx-large’, or an absolute font size.
icon_legend (bool, optional) – Whether to use icon but not color bar in legend. [Default False]
plot_anchor (str, optional) –
The alignment method of subplots. {'C', 'SW', 'S', 'SE', 'E', 'NE', 'N', 'NW', 'W'}

See details in https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.set_anchor.html

[Default ‘W’]
plots (dict, optional) –
Position and parameters of Waffle class for subplots in a dict, with format like {pos: {subplot_args: values, }, }.

Pos could be a tuple of three integers, where the first is the number of rows, the second the number of columns, and the third the index of the subplot.

Pos could also be a 3-digit number, as an int or a string. For example, 235 or ‘235’ means the 5th plot on a grid with 2 rows and 3 columns. All three digits must be less than 10 for this form to work.

The parameters of subplots are the same as Waffle class parameters, excluding plots itself.

If any parameter of subplots is not assigned, it use the same parameter in Waffle class as default value.
vertical (bool, optional) – Whether to draw the plot vertically or horizontally. [Default False]
starting_location (str, optional) –
Change the starting location plotting the blocks. {'NW', 'SW', 'NE', 'SE'}

’NW’ starts from the upper-left, ‘SW’ from the lower-left, ‘NE’ from the upper-right and ‘SE’ from the lower-right.

[Default ‘SW’]
rounding_rule (str, optional) –
The rounding rule applied when adjusting values to fit the chart size. {'nearest', 'floor', 'ceil', 'float'}

When it’s ‘nearest’, it is “round to nearest, ties to even” rounding mode;

When it’s ‘floor’, it rounds to less of the two endpoints of the interval;

When it’s ‘ceil’, it rounds to greater of the two endpoints of the interval;

When it’s ‘float’, values are not rounded at all. Blocks are partially filled where a category ends part way through one, and a block containing a boundary between two categories is split between their colors. The number of blocks then depends only on the total of the values, so charts of equal total are the same size.

’float’ draws partially filled rectangles and cannot be combined with icons or characters, which cannot be partially filled.

[Default ‘nearest’]
tight (bool|dict, optional) –
Set whether and how .tight_layout is called when drawing.

It could be bool or dict with keys “pad”, “w_pad”, “h_pad”, “rect” or None

If a bool, sets whether to call .tight_layout upon drawing.

If None, use the figure.autolayout param instead.

If a dict, pass it as kwargs to .tight_layout, overriding the default paddings.

[Default True]
background_color (str, optional) –
Color filling the space behind the blocks, including the gaps between them.

One rectangle is drawn behind the whole grid, so this works for any block shape and any interval ratio, and it applies to icons and characters as well as rectangle blocks.

[Default None, no background]
block_edge_color (str, optional) –
Color of the border drawn around each block.

Only applies to rectangle blocks. Icons and characters are text and have no such border.

The blank cells that block_arranging_style='new-line' pads a category’s line with get no border either, so a padded line still ends where its value ends.

[Default None, the border matches the block color]
block_edge_width (float, optional) –
Width of the border drawn around each block, in points.

[Default None, matplotlib’s patch line width]
show_values (bool|str, optional) –
Append each category’s value to its legend label, as Label (value).

True or 'value' shows the value itself;

'percentage' shows the category’s share of the total.

[Default False]
value_format (str, optional) –
Format string for the number added by show_values.

For example '{:.2f}%' or '{:,.0f} units'.

Defaults to '{:g}' for values and '{:.1f}%' for percentages.
sort_values (bool|str, optional) –
Order the categories by value.

True or 'desc' sorts largest first; 'asc' sorts smallest first. The string is case insensitive, as every other string argument is.

Every per-category argument - labels, colors, icons, characters and icon_style - is reordered along with the values.

[Default False]
block_arranging_style (string, optional) –
Set how to arrange blocks. {'normal', 'snake', 'new-line'}

If it is ‘normal’, it draws blocks line by line with same direction.

If it is ‘snake’, it draws blocks with snake pattern.

If it is ‘new-line’, it starts a new line when drawing each category. This only works when just one of rows and columns is assigned, with vertical=False when rows is assigned or vertical=True when columns is assigned.

[Default ‘normal’]

classmethod make_waffle(ax: Axes, **kwargs)#

Plot waffle chart on given axis. Run it with codes like: Waffle.make_waffle(ax=ax, rows=5, values=[48, 46, 6])

Note that calling this method does not update attributes, including fig_args, plot_args, and values_len

Parameters:

ax (matplotlib.axes.Axes) – An instance of Matplotlib Axes
**kwargs – Waffle properties

Attributes:

Waffle.fig_args: Dict#: All Waffle-specific arguments with default values

Waffle.plot_args: List#: Standardized arguments of all subplots

Waffle.values_len: int | None#: The length of values