explore_spacetime_heatmap

explore_spacetime_heatmap(
    df,
    var,
    *,
    entity=None,
    time=None,
    gdf=None,
    sort_by='value',
    relative=False,
    title=None,
)

Draw one variable as an entity-by-time heatmap (every unit keeps its row).

The long panel is pivoted to one row per entity and one column per period and drawn as a heatmap on the library’s sequential scale, so persistence (rows that keep their shading left to right) and mobility (rows that change shade) are visible unit by unit.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Long panel holding var per entity and period.	required
var	str	Numeric column of df to draw.	required
entity	str | None	Panel identifiers; default to the ids declared via :func:geometrics.set_panel. Both are required.	None
time	str | None	Panel identifiers; default to the ids declared via :func:geometrics.set_panel. Both are required.	None
gdf	gpd.GeoDataFrame | None	Entity geometry, required for the geographic row orders (sort_by="north_south" / "east_west"); entities are matched on the gdf’s entity-id column.	None
sort_by	Literal['value', 'name', 'north_south', 'east_west']	Row order: "value" (mean value per unit, highest first), "name" (alphabetical), "north_south" (metric-CRS centroid latitude, north first) or "east_west" (centroid longitude, west first).	'value'
relative	bool	Divide each column by its period mean, so 1.0 marks the period average and shading compares units within a period rather than tracking the level.	False
title	str | None	Figure title. Defaults to a description built from the variable label.	None

Returns

Name	Type	Description
	SpacetimeHeatmapResult	Frozen result with df (the entity-by-time pivot in display order, entities as the index), the themed fig, and notes.

Raises

Name	Type	Description
	KeyError	If var is not a column of df.
	TypeError	If var is not numeric, or gdf is not a GeoDataFrame.
	ValueError	If the panel ids do not resolve, sort_by is unknown, a geographic sort is requested without a gdf, or no complete observations remain.

Examples

Heatmap of a small two-period panel:

import pandas as pd

from geometrics.spacetime import explore_spacetime_heatmap

df = pd.DataFrame(
    {
        "region": ["a", "b", "a", "b"],
        "year": [2000, 2000, 2010, 2010],
        "gdppc": [1.0, 2.0, 1.5, 2.5],
    }
)
res = explore_spacetime_heatmap(df, "gdppc", entity="region", time="year")
res.df.shape