explore_treemap_plot

source

explore_treemap_plot(
    df,
    *,
    path=None,
    size=None,
    color=None,
    entity=None,
    time=None,
    max_units=200,
    sample_seed=0,
    title=None,
    subtitle=None,
)

Treemap of a hierarchy sized by size, animated over time when available.

Nested rectangles show how a total is divided among the levels of path (e.g. countries within continents). On a panel each period becomes a frame, stepped through by a play button and a time slider; the color scale is held fixed across frames so shifts are comparable. Without a resolvable time id a single static treemap is drawn.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Data frame containing the hierarchy, value and (optionally) time columns.	required
path	list[str] \| str \| None	Hierarchy columns from root to leaf, e.g. `["continent", "country"]`. Defaults to the panel `entity` (a single level) when omitted.	`None`
size	str \| None	Numeric column mapped to rectangle area. When omitted, each leaf is sized by its row count.	`None`
color	str \| None	Optional column mapped to color: numeric → a fixed-range sequential colorbar; otherwise a stable discrete palette.	`None`
entity	str \| None	Cross-sectional (unit) id. Defaults to the panel `entity` declared via :func:`expdpy.set_panel`; used to default `path` and to label leaves `"Name (id)"` when an `entity_name` is declared.	`None`
time	str \| None	Time identifier that drives the animation. Defaults to the panel `time`; when neither is available the treemap is static.	`None`
max_units	int \| None	Cap on the number of distinct leaf units; above it a seeded random sample is drawn (once, so the same leaves appear in every period) and an :class:`expdpy.ExpdpyWarning` is emitted. `None` disables sampling.	`200`
sample_seed	int	Seed for the leaf sample.	`0`

Returns

Name	Type	Description
	TreemapPlotResult	`df` (the complete-case frame plotted) and `fig` (the Plotly treemap).

Raises

Name	Type	Description
	ValueError	If no hierarchy can be resolved, `size` is non-numeric, or nothing remains after dropping incomplete rows.

Examples

World population by continent and country, colored by life expectancy, animated over the years:

import expdpy as ex
from expdpy.data import load_gapminder, load_gapminder_data_def

df = ex.set_labels(load_gapminder(), load_gapminder_data_def(), set_panel=True)
ex.explore_treemap_plot(
    df, path=["continent", "country"], size="pop", color="lifeExp", time="year"
).fig