How do kdims work for polygons in geoviews?

In http://geo.holoviews.org/user_guide/Geometries.html the line

gv.Polygons(world, vdims='pop_est')

yields a world map with polygons shaded by population, and I think what it's somehow doing is getting lat/long as the kdims but I don't understand how this works. If I try to specify 'geometry' as the kdims I get an error "Expected two kdims to use GeoDataFrame, found 1."

My end goal is to be able specify the kdims so that I can also specify a "year" parameter as the kdims and get a scrollbar on the map.

Answer

The behavior you are observing with gv.Polygons(world, vdims='pop_est') in GeoViews leverages GeoPandas' support for geographic data, where geometry is implicitly understood as the spatial dimension, and additional columns (like pop_est) are treated as value dimensions (vdims). Here's an explanation of how kdims and vdims work and how you can adapt them to achieve your goal of adding a "year" parameter with a slider:

Understanding kdims and vdims in GeoViews

1. kdims (Key Dimensions):

   • Represent the independent variables of your data.
   • For geographic data, GeoViews automatically infers kdims as latitude (y) and longitude (x) when using a GeoDataFrame, without requiring you to explicitly specify them.

2. vdims (Value Dimensions):

   • Represent dependent variables (attributes) used to color or scale your geometries (e.g., pop_est in your case).

Why does specifying 'geometry' as kdims fail?

geometry in a GeoDataFrame is treated as a column containing spatial data. GeoViews expects the spatial dimensions to be two separate kdims: x (longitude) and y (latitude). If you specify kdims=['geometry'], GeoViews cannot map it to the expected latitude and longitude dimensions, hence the error.

Adding a "year" Dimension with a Slider

To achieve your goal of adding a "year" parameter, you need to structure your data such that the year becomes an additional kdims. Here's how you can do it:

Steps:

1. Prepare Your Data:

   • Ensure your data is a GeoDataFrame with a geometry column for spatial data and additional columns for year and the variable of interest (e.g., pop_est).

2. Use HoloViews HoloMap for Interactive Widgets:

   • Convert your data into a format where each unique year corresponds to a separate set of polygons.
   • Use HoloMap to map the year dimension to a slider.

Example Code:

import geopandas as gpd
import geoviews as gv
import holoviews as hv
from holoviews import opts

gv.extension('bokeh')

# Example GeoDataFrame
world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))

# Add a dummy 'year' column for demonstration (e.g., duplicate data for multiple years)
years = [2000, 2010, 2020]
world_repeated = gpd.GeoDataFrame(
    pd.concat([world.assign(year=year) for year in years], ignore_index=True)
)

# Create a dictionary of HoloMaps, mapping 'year' to polygons
polygons_by_year = {
    year: gv.Polygons(world_repeated[world_repeated['year'] == year], vdims='pop_est')
    for year in years
}

# Combine into a HoloMap
polygons_hmap = hv.HoloMap(polygons_by_year, kdims='year')

# Customize plot options
polygons_hmap.opts(
    opts.Polygons(cmap='Viridis', colorbar=True, tools=['hover'], width=800, height=500)
)

Key Notes:

1. Why Use HoloMap?

   • HoloMap allows you to add interactive widgets like sliders. The kdims parameter in HoloMap defines the dimensions controlled by the widgets.

2. What Happens Behind the Scenes?

   • GeoViews recognizes the geometry column for spatial data and treats other columns (e.g., year and pop_est) as dimensions. When year is specified as a kdims, it creates a mapping between the year and its corresponding polygons.

3. Widget Interactivity:

   • With HoloMap, a slider for year will automatically be created when you render the map in a Jupyter Notebook or other interactive environment.

Output:

The map will display polygons shaded by pop_est, and you can use the slider to switch between years. This approach can be extended to other dimensions (e.g., additional variables or categories).