Skip to content

Use the Titanic dataset for every README example #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gyli merged 2 commits into from
Sep 17, 2026
Merged

Use the Titanic dataset for every README example #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
55df83b
Use the Titanic dataset for every README example
gyli Sep 17, 2026
4dd06d2
Drop the snake arrangement from README example 3
gyli Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 58 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,8 @@ existing layout.

## Examples

Every example below uses the same dataset as the quickstart: the people aboard the Titanic.

### 1. Value Scaling

```python
Expand All @@ -123,18 +125,18 @@ from pywaffle import Waffle

```python
fig = plt.figure(
FigureClass=Waffle,
rows=5,
columns=10,
values=[48, 46, 6],
FigureClass=Waffle,
rows=5,
columns=10,
values=[325, 285, 706, 885],
figsize=(5, 3)
)
plt.show()
```

![basic](examples/readme/basic.svg)

The values are automatically scaled to 24, 23 and 3 to fit 5 * 10 chart size.
Those are the first class, second class, third class and crew counts, 2,201 people in all. They are automatically scaled to 7, 6, 16 and 20 to fit the 5 * 10 chart size, so one block stands for about 22 people.

`FigureClass` and `figsize` are parameters of `matplotlib.pyplot.figure`, you may find the full parameter list on [matplotlib.pyplot.figure](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.figure.html) function reference.

Expand All @@ -143,7 +145,7 @@ Other parameters, including `rows`, `columns`, and `values` in this example, are
### 2. Values in dict & Auto-sizing

```python
data = {'Cat1': 10, 'Cat2': 7, 'Cat3': 9}
data = {'First class': 6, 'Second class': 24, 'Third class': 79}
fig = plt.figure(
FigureClass=Waffle,
rows=5,
Expand All @@ -155,25 +157,27 @@ plt.show()

![Use values in dictionary; use absolute value as block number, without defining columns](examples/readme/absolute_block_numbers.svg)

These are the children aboard, so here one block really is one child.

In this example, only `rows` is specified and `columns` is empty, absolute values in `values` are used as block numbers. Similarly, `rows` could also be optional if `columns` is specified.

If `values` is a dict, the keys will be used as labels in the legend.

### 3. More style settings including Legend, Title, Colors, Direction, Arranging Style, etc.
### 3. More style settings including Legend, Title, Colors, Direction, etc.

```python
data = {'Car': 58, 'Pickup': 21, 'Truck': 11, 'Motorcycle': 7}
data = {'First class': 325, 'Second class': 285, 'Third class': 706, 'Crew': 885}
fig = plt.figure(
FigureClass=Waffle,
rows=5,
columns=10,
values=data,
colors=["#C1D82F", "#00A4E4", "#FBB034", '#6A737B'],
title={'label': 'Vehicle Sales by Vehicle Type', 'loc': 'left'},
labels=[f"{k} ({v}%)" for k, v in data.items()],
colors=["#c9a227", "#5f8a8b", "#b5653f", "#3d4f5d"],
title={'label': 'Who was aboard the Titanic', 'loc': 'left'},
labels=[f"{k} ({v})" for k, v in data.items()],
legend={'loc': 'lower left', 'bbox_to_anchor': (0, -0.4), 'ncol': len(data), 'framealpha': 0},
starting_location='NW',
vertical=True,
block_arranging_style='snake'
vertical=True
)
fig.set_facecolor('#EEEEEE')
plt.show()
Expand All @@ -185,30 +189,35 @@ Parameter `colors` allows you to change the block color, and it accepts a list o

Parameter `title` and `legend` accept the same parameters as in Matplotlib, [matplotlib.pyplot.title](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.title.html) and [matplotlib.pyplot.legend](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.legend.html).

Parameter `starting_location`, `vertical`, and `block_arranging_style` controls [Where to Start First Block](https://pywaffle.readthedocs.io/en/latest/examples/block_shape_spacing_location_direction_and_style.html#where-to-start-first-block), [Plotting Direction](https://pywaffle.readthedocs.io/en/latest/examples/block_shape_spacing_location_direction_and_style.html#plotting-direction), and [Where to Start Each Category](https://pywaffle.readthedocs.io/en/latest/examples/block_shape_spacing_location_direction_and_style.html#where-to-start-each-category).
Parameter `starting_location` and `vertical` control [Where to Start First Block](https://pywaffle.readthedocs.io/en/latest/examples/block_shape_spacing_location_direction_and_style.html#where-to-start-first-block) and [Plotting Direction](https://pywaffle.readthedocs.io/en/latest/examples/block_shape_spacing_location_direction_and_style.html#plotting-direction). Together they fill from the top left along each row, so the four groups read in order, the way a line of text does.

There is also `block_arranging_style`, which can start each category on a new line or lay the blocks out in a snake. See [Where to Start Each Category](https://pywaffle.readthedocs.io/en/latest/examples/block_shape_spacing_location_direction_and_style.html#where-to-start-each-category).

You may find more details under [Examples](https://pywaffle.readthedocs.io/en/latest/examples.html) section in PyWaffle Documentation.

### 4. Plot with Icons - Pictogram Chart

```python
data = {'Car': 58, 'Pickup': 21, 'Truck': 11, 'Motorcycle': 7}
data = {'Men': 1667, 'Women': 425, 'Children': 109}
fig = plt.figure(
FigureClass=Waffle,
rows=5,
columns=10,
values=data,
colors=["#c1d82f", "#00a4e4", "#fbb034", '#6a737b'],
colors=["#3d4f5d", "#c9a227", "#b5653f"],
legend={'loc': 'upper left', 'bbox_to_anchor': (1, 1)},
icons=['car-side', 'truck-pickup', 'truck', 'motorcycle'],
font_size=12,
icons=['person', 'person-dress', 'child'],
font_size=18,
icon_legend=True
)
plt.show()
```

![Use Font Awesome icons](examples/readme/fontawesome.svg)

PyWaffle supports [Font Awesome](https://fontawesome.com/) icons in the chart. See [Plot with Characters or Icons](https://pywaffle.readthedocs.io/en/latest/examples/plot_with_characters_or_icons.html) for details.
The same 2,201 people, cut by group instead of by class. One figure stands for about 44 of them.

PyWaffle supports [Font Awesome](https://fontawesome.com/) icons in the chart. Font Awesome is an optional dependency, installed with `pip install "pywaffle[icons]"`. See [Plot with Characters or Icons](https://pywaffle.readthedocs.io/en/latest/examples/plot_with_characters_or_icons.html) for details.

### 5. Plotting on Existed Figure and Axis

Expand All @@ -224,70 +233,76 @@ Waffle.make_waffle(
ax=ax, # pass axis to make_waffle
rows=5,
columns=10,
values=[30, 16, 4],
title={"label": "Waffle Title", "loc": "left"}
values=[710, 1491],
title={"label": "Survived and lost", "loc": "left"}
)
```

![Plotting on Existed Figure and Axis](examples/readme/existed_axis.svg)

710 of the 2,201 aboard survived.

### 6. Multiple Plots in One Chart

```python
import pandas as pd
data = pd.DataFrame(
{
'labels': ['Car', 'Truck', 'Motorcycle'],
'Factory A': [32384, 13354, 5245],
'Factory B': [22147, 6678, 2156],
'Factory C': [8932, 3879, 896],
'labels': ['Men', 'Women', 'Children'],
'First class': [175, 144, 6],
'Second class': [168, 93, 24],
'Third class': [462, 165, 79],
},
).set_index('labels')

# A glance of the data:
# Factory A Factory B Factory C
# First class Second class Third class
# labels
# Car 27384 22147 8932
# Truck 7354 6678 3879
# Motorcycle 3245 2156 1196
# Men 175 168 462
# Women 144 93 165
# Children 6 24 79

fig = plt.figure(
FigureClass=Waffle,
plots={
311: {
'values': data['Factory A'] / 1000, # Convert actual number to a reasonable block number
'labels': [f"{k} ({v})" for k, v in data['Factory A'].items()],
'values': data['First class'] / 10, # Convert actual number to a reasonable block number
'labels': [f"{k} ({v})" for k, v in data['First class'].items()],
'legend': {'loc': 'upper left', 'bbox_to_anchor': (1.05, 1), 'fontsize': 8},
'title': {'label': 'Vehicle Production of Factory A', 'loc': 'left', 'fontsize': 12}
'title': {'label': 'First class', 'loc': 'left', 'fontsize': 12}
},
312: {
'values': data['Factory B'] / 1000,
'labels': [f"{k} ({v})" for k, v in data['Factory B'].items()],
'legend': {'loc': 'upper left', 'bbox_to_anchor': (1.2, 1), 'fontsize': 8},
'title': {'label': 'Vehicle Production of Factory B', 'loc': 'left', 'fontsize': 12}
'values': data['Second class'] / 10,
'labels': [f"{k} ({v})" for k, v in data['Second class'].items()],
'legend': {'loc': 'upper left', 'bbox_to_anchor': (1.05, 1), 'fontsize': 8},
'title': {'label': 'Second class', 'loc': 'left', 'fontsize': 12}
},
313: {
'values': data['Factory C'] / 1000,
'labels': [f"{k} ({v})" for k, v in data['Factory C'].items()],
'legend': {'loc': 'upper left', 'bbox_to_anchor': (1.3, 1), 'fontsize': 8},
'title': {'label': 'Vehicle Production of Factory C', 'loc': 'left', 'fontsize': 12}
'values': data['Third class'] / 10,
'labels': [f"{k} ({v})" for k, v in data['Third class'].items()],
'legend': {'loc': 'upper left', 'bbox_to_anchor': (1.05, 1), 'fontsize': 8},
'title': {'label': 'Third class', 'loc': 'left', 'fontsize': 12}
},
},
rows=5, # Outside parameter applied to all subplots, same as below
cmap_name="Accent", # Change color with cmap
rounding_rule='ceil', # Change rounding rule, so value less than 1000 will still have at least 1 block
rounding_rule='ceil', # Change rounding rule, so a value under 10 still gets at least 1 block
figsize=(6, 5)
)

fig.suptitle('Vehicle Production by Vehicle Type', fontsize=14, fontweight='bold')
fig.supxlabel('1 block = 1000 vehicles', fontsize=8, x=0.14)
fig.suptitle('Titanic passengers by class', fontsize=14, fontweight='bold')
fig.supxlabel('1 block = 10 people', fontsize=8, x=0.14)
fig.set_facecolor('#EEEDE7')

plt.show()
```

![Multiple plots](examples/readme/multiple_plots.svg)

Each subplot is sized by its own class, so the widths show at a glance that third class carried more people than first and second combined.

> Figures throughout from the British Board of Trade inquiry of 1912: 2,201 aboard, 710 saved, 1,491 lost. Tabulated at [Sinking of the Titanic](https://en.wikipedia.org/wiki/Sinking_of_the_Titanic#Casualties_and_survivors).

## Demo

Wanna try it yourself? There is [Online Demo](https://mybinder.org/v2/gh/gyli/PyWaffle/master?filepath=demo.ipynb)!
Expand Down
Loading