explore_animated_scatter_plot

source

explore_animated_scatter_plot(
    df,
    x,
    y,
    *,
    size=None,
    color=None,
    entity=None,
    time=None,
    alpha=0.8,
    log_x=False,
    log_y=False,
    title=None,
    subtitle=None,
)

Animated bubble scatter of y against x over time (a Gapminder-style view).

Each period becomes a frame; a play button and slider step through them. Bubbles are sized by size and colored by color (discrete → one series per level with a legend; numeric → a colorbar). Axis ranges and the bubble size scale are fixed across all frames so movement is comparable from period to period.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Data frame containing the variables (a panel with a time identifier).	required
x	str	Column names for the axes (both must be numeric).	required
y	str	Column names for the axes (both must be numeric).	required
size	str \| None	Optional numeric column mapped to bubble area.	`None`
color	str \| None	Optional column mapped to bubble color (numeric → colorbar, otherwise discrete series).	`None`
entity	str \| None	Cross-sectional (unit) identifier, used for hover labels. Defaults to the panel `entity` declared via :func:`expdpy.set_panel`.	`None`
time	str \| None	Time identifier that drives the animation frames. Defaults to the panel `time`; an explicit value or a declared panel is required.	`None`
alpha	float	Bubble opacity (default `0.8`).	`0.8`
log_x	bool	Put the corresponding axis on a log scale (default `False`). Handy for heavy-tailed quantities such as GDP per capita — the canonical Gapminder x-axis.	`False`
log_y	bool	Put the corresponding axis on a log scale (default `False`). Handy for heavy-tailed quantities such as GDP per capita — the canonical Gapminder x-axis.	`False`
title	str \| None	Optional figure title.	`None`

Returns

Name	Type	Description
	AnimatedScatterResult	`df` (the complete-case frame plotted) and `fig` (the animated Plotly figure).

Raises

Name	Type	Description
	ValueError	If no time identifier can be resolved, or `x` / `y` are non-numeric.

Examples

The classic Gapminder animation — income on the x-axis, life expectancy on the y-axis, bubbles sized by population and colored by continent, moving across 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_animated_scatter_plot(
    df, x="gdpPercap", y="lifeExp", size="pop", color="continent"
).fig