Treemap Plot

Treemap plots are a data visualization technique used to represent hierarchical data in a space-filling manner. They display data as nested rectangles or squares, where the size and color of each rectangle represent the values or categories within the hierarchy. Developers can create treemaps to provide users with an efficient and visually intuitive way to explore hierarchical data structures and understand relationships between categories and subcategories, making them a valuable tool for various applications that involve hierarchical data presentation, analysis, and exploration.

Treemap plots are appropriate when the data have a hierarchical structure. Each level of the hierarchy consists of a categorical variable and an associated numeric variable with a value for each unique category.

What are treemap plots useful for?

Visualizing hierarchical data: Treemap plots are valuable for visualizing hierarchical data structures with multiple levels of nested categories or relationships. Developers can use treemaps to represent data in a space-efficient manner, making them suitable for applications where data has complex hierarchical organizations.
Hierarchical data comparison: Treemaps can be used to compare data within hierarchical structures, allowing users to understand the distribution of categories and their relative sizes. Developers can implement features that enable users to compare data across multiple hierarchies or time periods.
Data summarization: Treemaps are effective for summarizing large amounts of hierarchical data into a compact, visual format. Developers can use treemaps to provide users with an overview of hierarchical data, and users can drill down into specific categories for more detailed information.

Examples

A basic treemap plot

Visualize a hierarchical dataset as nested rectangles, with the size of each rectangle corresponding to a value for a particular group. Use the names argument to specify the column name for each group’s labels, the values argument to specify the column name for each group’s values, and the parents column to specify the root category of the chart.

import deephaven.plot.express as dx
gapminder = dx.data.gapminder()

# create table of only the most recent year of data, compute total population for each continent
gapminder_recent = (
    gapminder
    .last_by("Country")
    .view(["Continent", "Pop"])
    .sum_by("Continent")
    .update("World = `World`")
)

treemap_plot = dx.treemap(gapminder_recent, names="Continent", values="Pop", parents="World")

A treemap plot with `path`

Instead of manually aggregating and passing in names and parents, use the path argument to specify the hierarchy of the data. The first column is the root category, and the last column is the leaf category. The values are automatically summed up.

import deephaven.plot.express as dx

gapminder = dx.data.gapminder().update_view("World = `World`")

treemap_path_plot = dx.treemap(gapminder, path=["World", "Continent", "Country"], values="Pop")

A nested treemap plot with branch values

By default, the branchvalues argument is set to "remainder". Keep the default if the values column should be added to the sum of its children to get the value for a node. If the values column is equal to the sum of its children, set branchvalues to "total".

import deephaven.plot.express as dx
from deephaven import merge

data = dx.data.gapminder(ticking=False)

countries = data.last_by("Country").view(["Name=Country", "Pop", "Parent=Continent"])

# Sum country population by continent
continents = (
    countries.drop_columns("Name")
    .sum_by("Parent")
    .view(["Name=Parent", "Pop", "Parent=`World`"])
)

# Sum continent population
world = (
    continents.view("Pop").sum_by().view(["Name=`World`", "Pop", "Parent=(String)null"])
)

merged_gapminder = merge([world, continents, countries])

# Since the values column is equal to the sum of it's children, set branchvalues to "total"
treemap_nested = dx.treemap(
    merged_gapminder, names="Name", values="Pop", parents="Parent", branchvalues="total"
)

API Reference

Returns a treemap chart

Returns: DeephavenFigure A DeephavenFigure that contains the treemap chart

Parameters	Type	Default	Description
table	Table \| DataFrame		A table to pull data from.
names	str \| None	None	The column containing names of the sections
values	str \| None	None	The column containing values of the sections
parents	str \| None	None	The column containing parents of the sections
ids	str \| None	None	The column containing ids of the sections. Unlike values, these must be unique. Values are used for ids if ids are not specified.
path	str \| list[str] \| None	None	A column or list of columns that describe the hierarchy. The first column is the root, the second column contains the children of the root, and so on. The last column is the leaf.
color	str \| list[str] \| None	None	A column or list of columns that contain color values. If only one column is passed, and it contains numeric values, the value is used as a value on a continuous color scale. Otherwise, the value is used for a plot by on color. If path is provided, only a single color column is allowed. See color_discrete_map for additional behaviors.
hover_name	str \| None	None	A column that contains names to bold in the hover tooltip.
labels	dict[str, str] \| None	None	A dictionary of labels mapping columns to new labels.
color_discrete_sequence	list[str] \| None	None	A list of colors to sequentially apply to the series. The colors loop, so if there are more series than colors, colors will be reused.
color_discrete_map	dict[str \| tuple[str], str] \| None	None	If dict, the keys should be strings of the column values (or a tuple of combinations of column values) which map to colors.
color_continuous_scale	list[str] \| None	None	A list of colors for a continuous scale
range_color	list[float] \| None	None	A list of two numbers that form the endpoints of the color axis
color_continuous_midpoint	float \| None	None	A number that is the midpoint of the color axis
title	str \| None	None	The title of the chart
template	str \| None	None	The template for the chart.
branchvalues	str \| None	None	Set to 'total' to take the value at a level to include all descendants and 'remainder' to the value as the remainder after subtracting leaf values.
maxdepth	int \| None	None	Sets the total number of visible levels. Set to -1 to render all levels.
unsafe_update_figure	Callable	<function default_callback>	An update function that takes a plotly figure as an argument and optionally returns a plotly figure. If a figure is not returned, the plotly figure passed will be assumed to be the return value. Used to add any custom changes to the underlying plotly figure. Note that the existing data traces should not be removed. This may lead to unexpected behavior if traces are modified in a way that break data mappings.
on_click	Callable[..., bool \| None] \| None	None	A callback function that is called when a point is clicked. The function receives a dict with 'points' (list of clicked point data) and 'modifiers' (keyboard state). On hierarchical charts (sunburst, treemap, icicle), return False to prevent drill-down. The return value is ignored on other chart types.
on_press	Callable[..., bool \| None] \| None	None	Alias for on_click.
on_double_click	Callable[..., None] \| None	None	A callback function that is called on double-click. The function receives a dict with 'modifiers' (keyboard state). Fires in zoom/pan mode only; in select mode, on_deselect fires instead.
on_double_press	Callable[..., None] \| None	None	Alias for on_double_click.
on_selected	Callable[..., None] \| None	None	A callback function that is called when a box or lasso selection completes. The function receives a dict with 'points' (list of selected point data), 'range' (for box select), and 'modifiers'.
on_deselect	Callable[..., None] \| None	None	A callback function that is called when the selection is cleared (e.g., by double-clicking on an empty area).
on_relayout	Callable[..., None] \| None	None	A callback function that is called when the chart layout changes due to user interaction (pan, zoom, axis reset, etc.). The function receives a dict of the layout keys that changed.
on_legend_click	Callable[..., bool \| None] \| None	None	A callback function that is called when a legend item is clicked. Return False to prevent the default trace visibility toggle. Return True or None to allow it.
on_legend_double_click	Callable[..., bool \| None] \| None	None	A callback function that is called when a legend item is double-clicked. Return False to prevent the default isolate/show-all toggle. Return True or None to allow it.
on_click_annotation	Callable[..., None] \| None	None	A callback function that is called when an annotation is clicked. The function receives a dict with 'index', 'annotation', and 'modifiers'.
on_web_gl_context_lost	Callable[..., None] \| None	None	A callback function that is called when the WebGL rendering context is lost (e.g., GPU reclaims resources).