Ranking chart

A chart which shows how the rank of something varies.

Usage

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

{% comp 'oi.chart.ranking', { "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 - An ordered array of columns to use to build the ranking chart. Each must have a name but these can also be virtual columns. This allows you to use fewer columns than exist in the data. There can also be an optional fillna which will be used in the tooltip in place of null or NaN values.
colours - Define some visualisation-specific named colours.
width - Set a specific width for the visualisation.
height - Set a specific height for the visualisation.
key - The title of the column that contains the things to be ranked.
circles - Add rank values on the lines by setting this in the range 0-1. The default is 0.
curvature - This sets the amount of curvature (between 0 and 1) for the line. The default is 1.
stroke-width - This can be in the range 0 and 1. The default is 0.5.
font-size - Sets the size of the font to use.
colour - The title of the column to use to set the colour of each line. The value can either be a hex colour value or use a colour scale.
scale - A colour scale to use to set a line's stroke colour.
min - Used with scale and max to define the colour scale.
max - Used with scale and min to define the colour scale.
legend - Define the legend
top - Limit the visualisation to the top x. Note that because things can move in and out of the top 10 the chart will also show those as a compressed group underneath.
gap - (number) The size of the gap between any top x and the compressed group below. The default is 1.
divider - (object) The SVG properties of the dividing line.
tooltip - This is to add tooltips to days. Either provide the name of an existing/virtual column in the data or construct one using string templates.
reverse - (boolean) By default the ranking is by the lowest value. However you can set it to use the highest value as the ranking by setting this to true.
attribution - Add a line of attribution text under the visualisation.

1. Simple ranking chart§

Embeddable version

Series are created by referencing a column in the data using key e.g. the Country column. They will be ranked by the first item in columns.

This example was made with config:

YAML

data: test.data.heatmap
key: Country
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'

JSON

{
	"data": "test.data.heatmap",
	"key": "Country",
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}]
}

2. Customise the lines§

Embeddable version

The curvature of the lines can be in the range 0-1 (default of 1). The stroke-width can be in the range 0-1 (default of 0.5). You can add ranks on the lines by setting circle in the range 0-1 (default of 0).

This example was made with config:

YAML

data: test.data.heatmap
key: Country
circles: 0.9
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'
curvature: 0
stroke-width: 0.2
font-size: 24

JSON

{
	"data": "test.data.heatmap",
	"key": "Country",
	"circles": 0.9,
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}],
	"curvature": 0,
	"stroke-width": 0.2,
	"font-size": 24
}

3. Coloured lines§

Embeddable version

The colour of each series can be scaled by the column referenced by colour. This column contains a colour as a text string. In this example we will also add circles showing the ranks.

Key: Asia Australia Europe N. America S. America

This example was made with config:

YAML

colours:
  test: '#999000'
data: test.data.heatmap
key: Country
colour: Colour
circles: 0.9
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'

JSON

{
	"colours": {
		"test": "#999000"
	},
	"data": "test.data.heatmap",
	"key": "Country",
	"colour": "Colour",
	"circles": 0.9,
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}]
}

4. Lines coloured using a scale§

Embeddable version

We can use a colour scale along with a colour column in the data (with optional min and max values) to set the colour using numeric values. In this case we will use the initial rank (found in the Ranks→2018 column) to set the colours.

This example was made with config:

YAML

data: test.data.heatmap
key: Country
colour: Ranks→2018
scale: Viridis
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'

JSON

{
	"data": "test.data.heatmap",
	"key": "Country",
	"colour": "Ranks→2018",
	"scale": "Viridis",
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}]
}

5. Add a legend§

Embeddable version

This example was made with config:

YAML

data: test.data.heatmap
key: Country
colour: Ranks→2018
scale: Viridis
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'
legend:
  show: true
  position: top
  items:
    - value: 40
      label: 40
    - value: 30
      label: 30
    - value: 20
      label: 20
    - value: 10
      label: 10
    - value: 1
      label: 1

JSON

{
	"data": "test.data.heatmap",
	"key": "Country",
	"colour": "Ranks→2018",
	"scale": "Viridis",
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}],
	"legend": {
		"show": true,
		"position": "top",
		"items": [{
				"value": 40,
				"label": 40
			},{
				"value": 30,
				"label": 30
			},{
				"value": 20,
				"label": 20
			},{
				"value": 10,
				"label": 10
			},{
				"value": 1,
				"label": 1
			}]
	}
}

6. Limit to the top x entries§

Embeddable version

It may be that we have a long list of entries and we only want to show the top few. We can limit the visualisation using e.g. top: 10 to get the top 10. But note that because things can move in and out of the top 10 the chart will also show those as a compressed group underneath. We will assign colours based on the Ranks→2020 column in the data so we'll also set the max value to 10. To help make things clearer, we'll also add rank circles and make the stroke-width narrower.

This example was made with config:

YAML

data: test.data.heatmap
key: Country
colour: Ranks→2020
max: 10
scale: Viridis
circles: 0.9
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'
top: 10
stroke-width: 0.2

JSON

{
	"data": "test.data.heatmap",
	"key": "Country",
	"colour": "Ranks→2020",
	"max": 10,
	"scale": "Viridis",
	"circles": 0.9,
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}],
	"top": 10,
	"stroke-width": 0.2
}

7. Limit to the bottom x entries§

Embeddable version

It may be that we have a long list of entries and we only want to show the bottom few. We make use of top: 10 but set reverse: true to change the direction on which the rank is calculated. As things can move in and out of the bottom group, the chart will also show those as a compressed group underneath. We will assign colours based on the Ranks→2020 column in the data so we'll also set the max value to 10. To help make things clearer, we'll also add rank circles and make the stroke-width narrower.

This example was made with config:

YAML

data: test.data.heatmap
key: Country
colour: Ranks→2020
scale: Viridis
circles: 0.9
debug: true
columns:
  - name: 2018
    template: '{{ Ranks→2018 }}'
  - name: 2019
    template: '{{ Ranks→2019 }}'
  - name: 2020
    template: '{{ Ranks→2020 }}'
reverse: true
max: 10
top: 10
stroke-width: 0.2

JSON

{
	"data": "test.data.heatmap",
	"key": "Country",
	"colour": "Ranks→2020",
	"scale": "Viridis",
	"circles": 0.9,
	"debug": true,
	"columns": [{
			"name": 2018,
			"template": "{{ Ranks→2018 }}"
		},{
			"name": 2019,
			"template": "{{ Ranks→2019 }}"
		},{
			"name": 2020,
			"template": "{{ Ranks→2020 }}"
		}],
	"reverse": true,
	"max": 10,
	"top": 10,
	"stroke-width": 0.2
}

8. A more complex example§

Embeddable version

This uses a dataset of private sector long term empty properties by ward in Leeds taken from Data Mill North. The CSV file contains the percentage of empty properties in each ward by month. We find the rank for each key (e.g. Ward) in each of the columns. As we want larger percentages to give lower ranks, we set reverse to true. We colour the lines by the ranking of the 2019 column in the data by referring to 2019_rank.

This example was made with config:

YAML

data: test.data.dmn-lcc-private-sector-long-term-empties
key: Ward
colour: 2019_rank
scale: Viridis
stroke-width: 0.75
reverse: true
columns:
  - name: '2009'
    template: '{{ Jan-09 % }}'
  - name: '2010'
    template: '{{ Jan-10 % }}'
  - name: '2011'
    template: '{{ Jan-11 % }}'
  - name: '2012'
    template: '{{ Jan-12 % }}'
  - name: '2013'
    template: '{{ Jan-13 % }}'
  - name: '2014'
    template: '{{ Jan-14 % }}'
  - name: '2015'
    template: '{{ Jan-15 % }}'
  - name: '2016'
    template: '{{ Jan-16 % }}'
  - name: '2017'
    template: '{{ Jan-17 % }}'
  - name: '2018'
    template: '{{ Jan-18 % }}'
  - name: '2019'
    template: '{{ Jan-19 % }}'

JSON

{
	"data": "test.data.dmn-lcc-private-sector-long-term-empties",
	"key": "Ward",
	"colour": "2019_rank",
	"scale": "Viridis",
	"stroke-width": 0.75,
	"reverse": true,
	"columns": [{
			"name": "2009",
			"template": "{{ Jan-09 % }}"
		},{
			"name": "2010",
			"template": "{{ Jan-10 % }}"
		},{
			"name": "2011",
			"template": "{{ Jan-11 % }}"
		},{
			"name": "2012",
			"template": "{{ Jan-12 % }}"
		},{
			"name": "2013",
			"template": "{{ Jan-13 % }}"
		},{
			"name": "2014",
			"template": "{{ Jan-14 % }}"
		},{
			"name": "2015",
			"template": "{{ Jan-15 % }}"
		},{
			"name": "2016",
			"template": "{{ Jan-16 % }}"
		},{
			"name": "2017",
			"template": "{{ Jan-17 % }}"
		},{
			"name": "2018",
			"template": "{{ Jan-18 % }}"
		},{
			"name": "2019",
			"template": "{{ Jan-19 % }}"
		}]
}