Treemap
Updated 6 years ago by Duncan Clark
How to use this template
This template is great for summarising your data across different categories and showing the result as a set of nested rectangles. (You can think of this template as a visual pivot table.)
Data requirements
The data should be in 'long-form' i.e. each row represents a single data-point and each column represents a variable. For example:
Film Genre Studio Worldwide Gross ($m)
27 Dresses Comedy Fox 160.31
(500) Days of Summer Comedy Fox 60.72
A Dangerous Method Drama Independent 8.97
A Serious Man Drama Universal 30.68
Across the Universe Romance Independent 29.37
Beginners Comedy Independent 14.31
Dear John Drama Sony 114.97
Usage
Columns can be seen as either categorical (e.g. Genre
and Studio
) or numeric (e.g. Worldwide Gross
).
Choose:
- categorical columns to nest your data by
- numeric columns to size the rectangles by
For example, if we wanted to know which studio took the most revenue we could nest by Studio
and size by Worldwide Gross
.
If we wanted to further break down each studio into genres, we could nest by Studio
and Genre
.
If 2 or more columns are chosen to nest you'll be able to zoom into a category by clicking. Zoom out by clicking the triangle that appears in the top right of the chart.
Examples
- EU Referendum spending
- EU Referendum spending (2 levels)
- HMRC Organogram
- Inc 5000 fastest growing companies
Tips
- You don't have to choose a column to size by, in which case the rectangles will be size by the count of data points.
- Click on the popup to freeze it. Click on it again to unfreeze.
- You can choose the number of visible hierachy levels. Try varying this within a story to gradually break down categories into sub-categories.
Credits
Created by Peter Cook and the Flourish team.
API information
This section documents API usage specific to this template, so for an introduction we suggest you refer to the generic API documentation instead.
template: _603
version: _16
Template data
There are three different formats in which you can supply data to this template. The most convenient for you to use likely depends on the source of your data, as described below.
1. Array of arrays, and a bindings object
You can supply arrays of arrays to opts.data
, which might look
like:
{ data: { data: [ [ "DataColumn1Value1", "DataColumn2Value1", [ "DataColumn1Value2", "DataColumn2Value2", [ "DataColumn1Value3", "DataColumn2Value3", ... ] } }
where each array of arrays represents the rows in a data sheet.
To tell the API how the values from each column should be
associated with the keys that the template is expecting, you must also supply
an object attached to opts.bindings
. (The meanings of the
keys in the bindings object are documented
below.) The minimal bindings you can
supply for this template are as shown in this example:
{ template: "_603", version: "_16", bindings: { data: { } }, data: { data: [ [ "DataColumn1Value1", "DataColumn2Value1", [ "DataColumn1Value2", "DataColumn2Value2", [ "DataColumn1Value3", "DataColumn2Value3", ... ] } }
All possible bindings that you can supply are shown in this example:
{ template: "_603", version: "_16", bindings: { data: { nest_columns: [0, 1, ...], // index(es) of column(s) in your data size_column: 2, // index of a column in your data filter: 3, // index of a column in your data } }, data: { data: [ [ "DataColumn1Value1", "DataColumn2Value1", [ "DataColumn1Value2", "DataColumn2Value2", [ "DataColumn1Value3", "DataColumn2Value3", ... ] } }
2. Array of objects with arbitrary keys, and a bindings object
This format is most likely useful when you have data from an external source,
such as CSV data loaded from d3-dsv.
You should supply this attached to the opts.data
, which might look
like:
{ data: [ { "DataHeader1": ..., "DataHeader2": ..., ... }, { "DataHeader1": ..., "DataHeader2": ..., ... }, { "DataHeader1": ..., "DataHeader2": ..., ... }, ... ] }
... but with the keys being the column headers from your
source data instead. You must also supply an object attached to
opts.bindings
. The minimal bindings you can
supply for this template are as shown in this example:
{ template: "_603", version: "_16", bindings: { data: { } }, data: { data: [ { "DataHeader1": ..., "DataHeader2": ..., ... }, { "DataHeader1": ..., "DataHeader2": ..., ... }, { "DataHeader1": ..., "DataHeader2": ..., ... }, ... ] } }
All possible bindings that you can supply are shown in this example:
{ template: "_603", version: "_16", bindings: { data: { nest_columns: ["DataHeader1", "DataHeader2", ...], size_column: "DataHeader3", filter: "DataHeader4", } }, data: { data: [ { "DataHeader1": ..., "DataHeader2": ..., ... }, { "DataHeader1": ..., "DataHeader2": ..., ... }, { "DataHeader1": ..., "DataHeader2": ..., ... }, ... ] } }
(As before, the keys containing "Header" would be replaced by column names from your data source.)
3. Array of objects with template-defined keys
There is an alternative format you can use, which is likely to be easier to
use if your data is not from a spreadsheet source. With this alternative format
you supply your data to the template as
an array of objects, attached to opts.data
, where the keys must
be those used by the template, as documented below. In this case
there is no need to supply a bindings object, since the key names are already
those expected by the template. The required properties in the data
object are as follows (scroll down for a
description of what each property is):
{ template: "_603", version: "_16", data: { data: [ { nest_columns: [...] }, ... ] }, ... }
And the full list of all possible properties is as follows:
{ template: "_603", version: "_16", data: { data: [ { nest_columns: [...], size_column: ..., filter: ... }, ... ] }, ... }
Meanings of the template data keys:
- data.nest_columns: nest_columns
- data.size_column: size_column
- data.filter: filter
Template settings
Options for opts.state
.
Header
header_title string
Title.
header_subtitle string
Subtitle.
header_color color
Color.
header_align string
Alignment. Allowed values:
header_margin number
Margin.
header_margin_advanced boolean
Advanced margin settings.
header_margin_top number
Top.
header_margin_right number
Right.
header_margin_bottom number
Bottom.
header_margin_left number
Left.
filter_type string
Control type. Allowed values:
filter_width number
Width.
controls_padding number
Margin.
filter_include_all boolean
Include “All” option.
filter_all_label string
“All” label.
Treemap
palette string
Colour scheme or custom colours. Choose from the list or enter a custom palette as a comma-separated list of colour codes or names (e.g. red, #343434) Allowed values:
aggregation_type string
Size cells by. Allowed values:
treemap_type string
Layout mode. Allowed values:
treemap_ratio number
Ratio.
cellPadding string
Padding. Add padding between hierarchy levels Allowed values:
num_of_visible_levels number
Visible Levels. How many hierarchy levels are visible at once? Min: 1
Popups
show_popups boolean
Show popups.
popup_text_color color
Text colour.
popup_bg_color color
Fill colour.
popup_opacity number
Fill opacity.
popup_separator string
Title separator.
popup_font_size number
Font size. Min: 1
popup_value_prefix string
Prefix.
popup_value_dp number
Decimal places.
popup_value_suffix string
Suffix.
Animations
animation_duration number
Duration. In seconds