GeoDatafier

GeoDatafier

Bases: BaseDatafier

Preprocesses wide-format geographic time-series data for choropleth animations.

The input data must be a GeoDataFrame containing a valid geometry column and time-series columns in wide format. The detected time columns are interpolated to the specified temporal frequency while all remaining columns are preserved.

---

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
ip_method	str	Interpolation method passed to DataFrame.interpolate(), by default "linear".	'linear'

interpolate_uneven(data, time_cols, time_format, ip_freq='5D', ip_method='time')

Interpolates wide-format temporal data to a uniform time frequency.

The input time columns are transposed into a datetime index, expanded to the requested interpolation frequency, interpolated, and finally converted back to wide format while preserving all non-temporal columns.

Parameters:

Name	Type	Description	Default
data	GeoDataFrame	Input GeoDataFrame containing static columns and wide-format time-series columns.	required
time_cols	list[str]	Names of the time-series columns to interpolate.	required
ip_freq	str	Target interpolation frequency passed to pandas.date_range(), by default "5D".	'5D'
ip_method	str	Interpolation method passed to DataFrame.interpolate(), by default "time".	'time'

Returns:

Type	Description
GeoDataFrame	GeoDataFrame containing the interpolated time-series columns along with the original static columns.

get_time_cols(data, time_format)

Identifies time-series columns from the dataframe.

Parameters:

Name	Type	Description	Default
data	DataFrame	Input dataframe.	required
time_format	str	Datetime format used to identify time columns.	required

Returns:

Type	Description
tuple[list[str], list[int]]	Detected time column names and their corresponding indices.

get_static_cols(data, time_columns)

Returns all non-temporal columns.

Parameters:

Name	Type	Description	Default
data	GeoDataFrame	Input GeoDataFrame.	required
time_columns	list[str]	Names of the detected time columns.	required

Returns:

Type	Description
list[str]	List containing the static (non-time) column names.

_get_masked_geo_annots(col_masks)

Internal helper to filter geometry annotations using column masks.

Filters the annotation data by retaining rows whose values match the provided values for each specified column. Multiple column masks are applied sequentially.

Parameters:

Name	Type	Description	Default
col_masks	dict[str, list]	Mapping of column names to the values to retain. Each column is filtered using Series.isin().	required

_get_filtered_geo_annots(filter_callback)

Internal helper to cache geometry annotations using a filter callback.

Applies filter_callback independently to each time column. Values replaced with NaN are omitted from geometry annotations.

Parameters:

Name	Type	Description	Default
filter_callback	Callable[[Series], Series]	Callback that receives a time column as a Series and returns the filtered Series.	required

_get_filtered_geo_annots(filter_callback)

Internal helper to cache geometry annotations using a filter callback.

Applies filter_callback independently to each time column. Values replaced with NaN are omitted from geometry annotations.

Parameters:

Name	Type	Description	Default
filter_callback	Callable[[Series], Series]	Callback that receives a time column as a Series and returns the filtered Series.	required