Skip to content

Choropleth

Choropleth

Bases: Baseplot

Choropleth animation module for visualizing temporal geographic data.

The data must be a GeoDataFrame containing a valid geometry column and time-series columns in wide format.

Expected input format:: 

    geometry      NAME       ISO_A3    2020    2021    2022
    -------------------------------------------------------
    POLYGON(...)  India      IND       1380    1395    1410
    POLYGON(...)  China      CHN       1439    1441    1443
    POLYGON(...)  Japan      JPN        126     125     124

Parameters:

Name Type Description Default
datafier GeoDatafier

GeoDatafier instance containing the interpolated geographic time-series data.

 required
post_update Callable[[Choropleth, int], None]

Callback function for additional customization.

 lambda self, i: None
vrange tuple[float, float]

Fixed value range (vmin, vmax) used for color normalization. If None, by default (min, max)

 None
cmap str

Matplotlib colormap used for the choropleth, by default "viridis".

 'viridis'
annot_geo_mask tuple[str, list]

Enables geometry annotations for features whose values in the specified column match the provided list.

Example: ("ISO_A3", ["IND", "USA", "CHN"])

 required
annot_geo_filter Callable[[Series], Series]

Callback applied independently to every time column to determine which geometries should be annotated.

The callback receives a Series representing one time column and should return a modified Series, replacing unwanted values with NaN.

Example: annot_geo_filter = lambda col: col.where(col >= col.nlargest(n).min(), np.nan)

 None
geo_annot_formatter Callable[[Number], str]

Function used to format geometry annotation values before rendering. Formatting is performed once during preprocessing and cached for the duration of the animation.

Default: human_readable

 human_readable
cbar_unit str

Unit appended to colorbar tick labels.

 ''
set_frame_on bool

Set whether the Axes rectangle patch is drawn., by default False

 False
post_update callback

The callback receives:

  • self : Choropleth instance
  • i : Current frame index

Example 

def post_update(self, i):
    self.ax.set_facecolor("#202020")
    self.ax.set_title(f"Frame {i}")

from_widedf(data, time_format, ip_freq, *, post_update=lambda self, i: None, vrange=None, log_norm=False, cmap='viridis', annot_geo_masks=None, annot_geo_filter=None, geo_annot_formatter=human_readable, cbar_unit='', set_frame_on=False) classmethod

Choropleth animation module for visualizing temporal geographic data.

The data must be a GeoDataFrame containing a valid geometry column and time-series columns in wide format.

Expected input format:: 

    geometry      NAME       ISO_A3    2020    2021    2022
    -------------------------------------------------------
    POLYGON(...)  India      IND       1380    1395    1410
    POLYGON(...)  China      CHN       1439    1441    1443
    POLYGON(...)  Japan      JPN        126     125     124

Parameters:

Name Type Description Default
data GeoDataFrame

Input GeoDataFrame containing geographic features and time-series columns.

 required
time_format str

Datetime format used to identify and parse time columns. For example, "%Y", "%Y-%m", or "%Y-%m-%d".

 required
ip_freq str

Interpolation frequency passed to pandas.date_range(). For example, "MS", "5D", or "1H".

 required
post_update Callable[[Choropleth, int], None]

Callback function for additional customization.

 lambda self, i: None
vrange tuple[float, float]

Fixed value range (vmin, vmax) used for color normalization. If None, by default (min, max)

 None
cmap str

Matplotlib colormap used for the choropleth, by default "viridis".

 'viridis'
annot_geo_mask tuple[str, list]

Enables geometry annotations for features whose values in the specified column match the provided list.

Example: ("ISO_A3", ["IND", "USA", "CHN"])

 required
annot_geo_filter Callable[[Series], Series]

Callback applied independently to every time column to determine which geometries should be annotated.

The callback receives a Series representing one time column and should return a modified Series, replacing unwanted values with NaN.

Example: annot_geo_filter = lambda col: col.where(col >= col.nlargest(n).min(), np.nan)

 None
geo_annot_formatter Callable[[Number], str]

Function used to format geometry annotation values before rendering. Formatting is performed once during preprocessing and cached for the duration of the animation.

Default: human_readable

 human_readable
cbar_unit str

Unit appended to colorbar tick labels.

 ''
post_update args
  • self : Choropleth instance
  • i : Current frame index

Example 

def post_update(self, i):
    self.ax.set_facecolor("#202020")
    self.ax.set_title(f"Frame {i}")

set_geo_plot(**kwargs)

Sets matplotlib keyword arguments for plotting the geographic data.

Parameters:

Name Type Description Default
**kwargs

Keyword arguments passed directly to GeoDataFrame.plot().

 {}

Examples:

plot.set_geo_plot(
    edgecolor="white",
    linewidth=0.5,
    alpha=0.9,
)

set_annot_geo(**kwargs)

Sets matplotlib keyword arguments for geometry annotations.

Parameters:

Name Type Description Default
**kwargs

Keyword arguments passed directly to Axes.annotate().

 {}
Example: 
plot.set_annot_geo(
    color="white",
    fontsize=10,
    ha="center",
)

set_cbar_ax(position='right', size='4%', pad=0.1, **kwargs)

Sets the position and properties of the colorbar axis.

Parameters:

Name Type Description Default
position str

Position of the colorbar relative to the plot, by default "right".

 'right'
size str

Width of the colorbar axis, by default "4%".

 '4%'
pad float

Padding between the plot and colorbar, by default 0.1.

 0.1
**kwargs

Additional keyword arguments passed to make_axes_locatable(...).append_axes().

 {}

set_cbar_ticks(tick_formatter=None, axis='both', which='both', length=0, **kwargs)

Sets the formatting and appearance of the colorbar ticks.

Parameters:

Name Type Description Default
tick_formatter Callable[[float, float], str]

Function used to format colorbar tick labels. Passed to matplotlib.ticker.FuncFormatter.

 None
axis str

Axis on which to apply the tick parameters, by default "both".

 'both'
which str

Specifies which ticks to modify ("major", "minor", or "both"), by default "both".

 'both'
length int

Tick length, by default 0.

 0
**kwargs

Additional keyword arguments passed to Axes.tick_params().

 {}

set_nan_geo(color='#62656B', **kwargs)

Sets the appearance of geometries with missing values.

Parameters:

Name Type Description Default
color str

Fill color used for geometries whose value is NaN, by default "#62656B".

 '#62656B'
**kwargs

Additional keyword arguments passed directly to GeoDataFrame.plot() when rendering missing-value geometries.

 {}
Example: 
plot.set_nan_geo(
    color="#444444",
    edgecolor="black",
    hatch="///",
)

_set_vrange(vmin=None, vmax=None)

Sets the color mapping range for the choropleth.

Parameters:

Name Type Description Default
vmin float

Minimum value for the colormap. By default, min value in the dataset.

 None
vmax float

Maximum value for the colormap. By default, max value in the dataset.

 None