Waffle chart Since 0.9.2

Display values as a percentage of a whole in an aesthetically pleasing way. A nicer alternative to pie charts.

Usage

To use this component in a Vento template you would add the following (assumes you've loaded OI Lume Viz into componentNamespace: 'oi'):

Vento

{{ comp.oi.chart.waffle({ "config": config }) }}

Nunjucks

{% comp 'oi.chart.waffle', { "config": config } %}{% endcomp %}

where config is replaced by an object that contains some or all of these variables:

data - Either a reference to a CSV file in the Lume site or an array of rows with named attributes
columns - As with many of the visualisation types you can optionally add virtual columns.
colours - Define some visualisation-specific named colours.
width - Set a specific width for the visualisation.
height - Set a specific height for the visualisation.
series - An ordered array of series. Each one is of the form:
- value - The title of the column to use for the value.
- colour - The hex code to use to colour this series.
- tooltip - Either a string, template string, or the column heading to use to build a tooltip.
- points - Properties of the points:
  - size - The size of the point.
  - marker - One of circle, triangle, square, diamond, pentagon, hexagon, octagon, line, or cross. Alternatively you could set a sub-property svg that is an SVG image as a string.
  - rotate - How much to rotate the marker around its centre by, in degrees.
total - The name of the column that contains a total value. If not provided it will be guessed from the sum of the series values.
padding - Set the padding between cells of the waffle.
size - Set the grid size of the waffle. The default is 10 which gives a 10x10 waffle. You can also specify an array with two values e.g. [20,5] to set waffle grid horizontally and vertically
rounding - By default the values are rounded using Math.round() but we can choose to use Math.floor() by setting rounding to floor (you could also use ceil).
direction - By default, the direction is set to l2r which means that values fill in from the left. If we set direction to r2l it will fill values from the right.
gravity - By default, the gravity is set to bottom which means that values start at the bottom and build upwards. We can also set gravity to top, left or right.
attribution - Add a line of attribution text under the visualisation.

1. Basic waffle chart§

Embeddable version

This is a basic waffle chart showing the percentage of people aged 75 and over who have had the 2023 Spring Booster of the COVID-19 vaccination in England (data from UK Health Security Agency). In this example the series→value is already given as a percentage.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}]
}

2. Set padding§

Embeddable version

We can set the padding between cells of the waffle.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
padding: 16

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"padding": 16
}

3. Set width/height§

Embeddable version

By default the waffle chart is 1080px across but we can set the width and/or height of the waffle to other values if we wish.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
width: 300

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"width": 300
}

4. Set waffle grid size§

Embeddable version

We can set the size, in grid cells, of the waffle grid.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
size: 5
width: 300

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"size": 5,
	"width": 300
}

5. Set waffle grid size in both dimensions§

Embeddable version

We can set the size, in grid cells, of the waffle grid horizontally and vertically.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
size:
  - 20
  - 5
width: 300

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"size": [
		20,
		5
	],
	"width": 300
}

6. Set the rounding type§

Embeddable version

By default the values are rounded using Math.round() but we can choose to use Math.floor() by setting rounding to floor (you could also use ceil). In this example it will mean 67 waffle cells are coloured in rather than 68.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
width: 300
rounding: floor

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"width": 300,
	"rounding": "floor"
}

7. Set direction§

Embeddable version

By default, the direction is set to l2r which means that values fill in from the left. If we set direction to r2l it will fill values from the right.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
direction: rtl
width: 300

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"direction": "rtl",
	"width": 300
}

8. Set gravity direction§

Embeddable version

By default, the gravity is set to bottom which means that values start at the bottom and build upwards. We can also set gravity to top, left or right.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
gravity: top
width: 300

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91"
		}],
	"gravity": "top",
	"width": 300
}

9. Add tooltips§

Embeddable version

In this example we will build a custom tooltip for the series. This can either refer to a column/virtual column in the data or be a string template.

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
series:
  - value: Percentage of people aged 75+
    colour: '#019c91'
    tooltip: >-
      Aged 75+

      People: {{ Total vaccinated aged 75+ | toLocaleString() }} ({{ Percentage
      of people aged 75+ }}%)
width: 300

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"series": [{
			"value": "Percentage of people aged 75+",
			"colour": "#019c91",
			"tooltip": "Aged 75+\nPeople: {{ Total vaccinated aged 75+ | toLocaleString() }} ({{ Percentage of people aged 75+ }}%)"
		}],
	"width": 300
}

10. Add legend§

Embeddable version

In this example, along with defining a width and creating a tooltip, we will add a legend to position→top.

Aged 75+ vaccinated

This example was made with config:

YAML

data:
  - Total vaccinated aged 75+: 3725152
    Percentage of people aged 75+: 67.9
columns:
  - name: Tooltip
    template: >-
      Aged 75+

      People: {{ Total vaccinated aged 75+ | toLocaleString() }} ({{ Percentage
      of people aged 75+ }}%)
series:
  - title: Aged 75+ vaccinated
    value: Percentage of people aged 75+
    colour: '#019c91'
    tooltip: Tooltip
width: 300
legend:
  show: true
  position: top

JSON

{
	"data": [{
			"Total vaccinated aged 75+": 3725152,
			"Percentage of people aged 75+": 67.9
		}],
	"columns": [{
			"name": "Tooltip",
			"template": "Aged 75+\nPeople: {{ Total vaccinated aged 75+ | toLocaleString() }} ({{ Percentage of people aged 75+ }}%)"
		}],
	"series": [{
			"title": "Aged 75+ vaccinated",
			"value": "Percentage of people aged 75+",
			"colour": "#019c91",
			"tooltip": "Tooltip"
		}],
	"width": 300,
	"legend": {
		"show": true,
		"position": "top"
	}
}

11. Show multiple series§

Embeddable version

In this example we show the gender breakdown of appearances on Channel 4's Taskmaster as of the end of series 15. We will create a tooltip for each series as virtual columns. In this example the data consists of appearances rather than percentages so we define a total key (to the column Total) in order to scale the values into percentages.

Other/diverse

Male

Female

This example was made with config:

YAML

data:
  - Female: 283
    Male: 675
    Other/diverse: 10
    Total: 968
total: Total
columns:
  - name: F tooltip
    template: >-
      Appearances: female

      {{ Female | toLocaleString() }} ({{ Female | multiply(100 / Total) |
      toFixed(1) | parseFloat }}%)
  - name: M tooltip
    template: >-
      Appearances: male

      {{ Male | toLocaleString() }} ({{ Male | multiply(100 / Total) |
      toFixed(1) | parseFloat }}%)
  - name: O tooltip
    template: >-
      Appearances: diverse/non-binary genders

      {{ Other/diverse | toLocaleString() }} ({{ Other/diverse | multiply(100 /
      Total) | toFixed(1) | parseFloat }}%)
series:
  - value: Female
    colour: '#722EA5'
    tooltip: F tooltip
  - value: Male
    colour: '#0dbc37'
    tooltip: M tooltip
  - value: Other/diverse
    colour: '#fac900'
    tooltip: O tooltip
size:
  - 20
  - 5
legend:
  show: true
  position: top

JSON

{
	"data": [{
			"Female": 283,
			"Male": 675,
			"Other/diverse": 10,
			"Total": 968
		}],
	"total": "Total",
	"columns": [{
			"name": "F tooltip",
			"template": "Appearances: female\n{{ Female | toLocaleString() }} ({{ Female | multiply(100 / Total) | toFixed(1) | parseFloat }}%)"
		},{
			"name": "M tooltip",
			"template": "Appearances: male\n{{ Male | toLocaleString() }} ({{ Male | multiply(100 / Total) | toFixed(1) | parseFloat }}%)"
		},{
			"name": "O tooltip",
			"template": "Appearances: diverse/non-binary genders\n{{ Other/diverse | toLocaleString() }} ({{ Other/diverse | multiply(100 / Total) | toFixed(1) | parseFloat }}%)"
		}],
	"series": [{
			"value": "Female",
			"colour": "#722EA5",
			"tooltip": "F tooltip"
		},{
			"value": "Male",
			"colour": "#0dbc37",
			"tooltip": "M tooltip"
		},{
			"value": "Other/diverse",
			"colour": "#fac900",
			"tooltip": "O tooltip"
		}],
	"size": [
		20,
		5
	],
	"legend": {
		"show": true,
		"position": "top"
	}
}

12. Change the markers§

Embeddable version

In this example we will set the points→marker values for each series. These can be one of circle, triangle, square, diamond, pentagon, hexagon, octagon, line, or cross. Each can have an optional rotate value set (in degrees) to rotate the shape.

Crosses

Hexagons

Triangles

This example was made with config:

YAML

data:
  - Triangles: 25
    Hexagons: 60
    Crosses: 15
total: 100
width: 300
columns:
  - name: triangle tooltip
    template: 'Triangles: {{ Triangles | toLocaleString() }}'
  - name: hexagon tooltip
    template: 'Hexagons: {{ Hexagons | toLocaleString() }}'
  - name: cross tooltip
    template: 'Crosses: {{ Crosses | toLocaleString() }}'
series:
  - value: Triangles
    colour: '#722EA5'
    tooltip: triangle tooltip
    points:
      marker: triangle
      rotate: 30
  - value: Hexagons
    colour: '#0dbc37'
    tooltip: hexagon tooltip
    points:
      marker: hexagon
  - value: Crosses
    colour: '#fac900'
    tooltip: cross tooltip
    points:
      marker: cross
legend:
  show: true
  position: top

JSON

{
	"data": [{
			"Triangles": 25,
			"Hexagons": 60,
			"Crosses": 15
		}],
	"total": 100,
	"width": 300,
	"columns": [{
			"name": "triangle tooltip",
			"template": "Triangles: {{ Triangles | toLocaleString() }}"
		},{
			"name": "hexagon tooltip",
			"template": "Hexagons: {{ Hexagons | toLocaleString() }}"
		},{
			"name": "cross tooltip",
			"template": "Crosses: {{ Crosses | toLocaleString() }}"
		}],
	"series": [{
			"value": "Triangles",
			"colour": "#722EA5",
			"tooltip": "triangle tooltip",
			"points": {
				"marker": "triangle",
				"rotate": 30
			}
		},{
			"value": "Hexagons",
			"colour": "#0dbc37",
			"tooltip": "hexagon tooltip",
			"points": {
				"marker": "hexagon"
			}
		},{
			"value": "Crosses",
			"colour": "#fac900",
			"tooltip": "cross tooltip",
			"points": {
				"marker": "cross"
			}
		}],
	"legend": {
		"show": true,
		"position": "top"
	}
}

13. Custom marker icons§

Embeddable version

In this example we show the breakdown of operating system share Mar 2023. We will create a tooltip for each series as virtual columns. In this example the data consists of appearances rather than percentages so we define a total in order to scale the values into percentages. We can set custom points→marker values for each series using SVG icons copied from Bootstrap icons. Note that because each series is rounded to the nearest whole bin, the totals don't add up to 100%.

Unknown

Linux

iOS/macOS

Windows

Android

This example was made with config:

YAML

data:
  - microsoft: 28.32
    apple: 24.33
    android: 41.48
    linux: 1.17
    other: 1.65
    unknown: 3.07
total: 100
columns:
  - name: microsoft tooltip
    template: 'Windows: {{ microsoft | toLocaleString() }}%'
  - name: apple tooltip
    template: 'iOS/macOS: {{ apple | toLocaleString() }}%'
  - name: android tooltip
    template: 'Android: {{ android | toLocaleString() }}%'
  - name: linux tooltip
    template: 'Linux: {{ linux | toLocaleString() }}%'
  - name: unknown tooltip
    template: 'Unknown: {{ unknown | toLocaleString() }}%'
  - name: other tooltip
    template: 'Other: {{ other | toLocaleString() }}%'
series:
  - value: android
    title: Android
    colour: '#a3c639'
    tooltip: android tooltip
    points:
      marker:
        svg: >-
          
  - value: microsoft
    title: Windows
    colour: '#0067b8'
    tooltip: microsoft tooltip
    points:
      marker:
        svg: >-
            
  - value: apple
    title: iOS/macOS
    colour: '#424243'
    tooltip: apple tooltip
    points:
      marker:
        svg: >-
          
  - value: linux
    title: Linux
    colour: '#f9be00'
    tooltip: linux tooltip
    points:
      marker:
        svg: >-
          
  - value: unknown
    title: Unknown
    colour: '#dfdfdf'
    tooltip: unknown tooltip
    points:
      marker:
        svg: >-
          
size:
  - 10
  - 10
width: 300
legend:
  show: true
  position: top

JSON

{
	"data": [{
			"microsoft": 28.32,
			"apple": 24.33,
			"android": 41.48,
			"linux": 1.17,
			"other": 1.65,
			"unknown": 3.07
		}],
	"total": 100,
	"columns": [{
			"name": "microsoft tooltip",
			"template": "Windows: {{ microsoft | toLocaleString() }}%"
		},{
			"name": "apple tooltip",
			"template": "iOS/macOS: {{ apple | toLocaleString() }}%"
		},{
			"name": "android tooltip",
			"template": "Android: {{ android | toLocaleString() }}%"
		},{
			"name": "linux tooltip",
			"template": "Linux: {{ linux | toLocaleString() }}%"
		},{
			"name": "unknown tooltip",
			"template": "Unknown: {{ unknown | toLocaleString() }}%"
		},{
			"name": "other tooltip",
			"template": "Other: {{ other | toLocaleString() }}%"
		}],
	"series": [{
			"value": "android",
			"title": "Android",
			"colour": "#a3c639",
			"tooltip": "android tooltip",
			"points": {
				"marker": {
					"svg": ""
				}
			}
		},{
			"value": "microsoft",
			"title": "Windows",
			"colour": "#0067b8",
			"tooltip": "microsoft tooltip",
			"points": {
				"marker": {
					"svg": "  "
				}
			}
		},{
			"value": "apple",
			"title": "iOS/macOS",
			"colour": "#424243",
			"tooltip": "apple tooltip",
			"points": {
				"marker": {
					"svg": ""
				}
			}
		},{
			"value": "linux",
			"title": "Linux",
			"colour": "#f9be00",
			"tooltip": "linux tooltip",
			"points": {
				"marker": {
					"svg": ""
				}
			}
		},{
			"value": "unknown",
			"title": "Unknown",
			"colour": "#dfdfdf",
			"tooltip": "unknown tooltip",
			"points": {
				"marker": {
					"svg": ""
				}
			}
		}],
	"size": [
		10,
		10
	],
	"width": 300,
	"legend": {
		"show": true,
		"position": "top"
	}
}

14. Set the empty markers§

Embeddable version

To set properties of the empty markers (the remainder of the grid), define a last series entry without a value. Note that creating an empty series will also cause a legend item to be created for it.

Not claiming

Claiming

This example was made with config:

YAML

data:
  - universal credit: 4
total: 100
columns:
  - name: uc tooltip
    template: >-
      Claiming Universal Credit or Jobseeker's Allowance: {{ universal credit |
      toLocaleString() }}%
series:
  - value: universal credit
    title: Claiming
    colour: '#ce0058'
    tooltip: uc tooltip
    points:
      marker:
        svg: >-
          
  - title: Not claiming
    colour: '#cccccc'
    points:
      marker:
        svg: >-
          
size:
  - 10
  - 10
width: 300
legend:
  show: true
  position: top

JSON

{
	"data": [{
			"universal credit": 4
		}],
	"total": 100,
	"columns": [{
			"name": "uc tooltip",
			"template": "Claiming Universal Credit or Jobseeker's Allowance: {{ universal credit | toLocaleString() }}%"
		}],
	"series": [{
			"value": "universal credit",
			"title": "Claiming",
			"colour": "#ce0058",
			"tooltip": "uc tooltip",
			"points": {
				"marker": {
					"svg": ""
				}
			}
		},{
			"title": "Not claiming",
			"colour": "#cccccc",
			"points": {
				"marker": {
					"svg": ""
				}
			}
		}],
	"size": [
		10,
		10
	],
	"width": 300,
	"legend": {
		"show": true,
		"position": "top"
	}
}