I want to create hexagons on my geographic map and want to preserve the digital boundary specified by the shapefile/geojson as well. How do I do it using uber's h3 python library?

I'm new to shapefiles or any other geographic data structures. I'm most comfortable with python.

tl;dr

For convenience, you can use H3-Pandas.

import geopandas as gpd
import h3pandas# Prepare data
gdf = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))
gdf = gdf.loc[gdf['continent'].eq('Africa')]
gdf['gdp_md_per_capita'] = gdf['gdp_md_est'].div(gdf['pop_est'])
resolution = 4# Resample to H3 cells
gdf.h3.polyfill_resample(resolution)

Full description

Use cases like this are precisely why I wrote H3-Pandas, an integration of H3 with Pandas and GeoPandas.

Let's use the naturalearth_lowres dataset included in GeoPandas to demonstrate the usage.

import geopandas as gpd
import h3pandaspath_shapefile = gpd.datasets.get_path('naturalearth_lowres')
gdf = gpd.read_file(path_shapefile)

Let's also create a numeric column for plotting.

gdf = gdf.loc[gdf['continent'].eq('Africa')]
gdf['gdp_md_per_capita'] = gdf['gdp_md_est'].div(gdf['pop_est'])

ax = gdf.plot(figsize=(15, 15), column='gdp_md_per_capita', cmap='RdBu')
ax.axis('off')

We will use H3 resolution 4. See the H3 resolution table for more details.

resolution = 4  

We can add H3 hexagons using the function polyfill. This method adds a list of H3 cells whose centroid falls into each polygon.

gdf_h3 = gdf.h3.polyfill(resolution)
print(gdf_h3['h3_polyfill'].head(3))1     [846aca7ffffffff, 8496b5dffffffff, 847b691ffff...
2     [84551a9ffffffff, 84551cdffffffff, 8455239ffff...
11    [846af51ffffffff, 8496e63ffffffff, 846a803ffff...
Name: h3_polyfill, dtype: object

If we want to explode the values horizontally (ending up with as many rows as there are H3 cells), we can use the parameter explode

gdf_h3 = gdf.h3.polyfill(resolution, explode=True)
print(gdf_h3.head(3))pop_est continent      name iso_a3  gdp_md_est  \
1  53950935    Africa  Tanzania    TZA    150600.0   
1  53950935    Africa  Tanzania    TZA    150600.0   
1  53950935    Africa  Tanzania    TZA    150600.0   geometry  gdp_md_per_capita  \
1  POLYGON ((33.90371 -0.95000, 34.07262 -1.05982...           0.002791   
1  POLYGON ((33.90371 -0.95000, 34.07262 -1.05982...           0.002791   
1  POLYGON ((33.90371 -0.95000, 34.07262 -1.05982...           0.002791   h3_polyfill  
1  846aca7ffffffff  
1  8496b5dffffffff  
1  847b691ffffffff  

We can then utilize the method h3_to_geo_boundary to obtain the geometries for the H3 cells. It expects that the index already has the H3 cell ids.

gdf_h3 = gdf_h3.set_index('h3_polyfill').h3.h3_to_geo_boundary()

We can now plot the result

ax = gdf_h3.plot(figsize=(15, 15), column='gdp_md_per_capita', cmap='RdBu')
ax.axis('off')

H3-Pandas actually has convenience function that performs all this at once: polyfill_resample

gdf_h3 = gdf.h3.polyfill_resample(resolution)
ax = gdf_h3.plot(figsize=(15, 15), column='gdp_md_per_capita', cmap='RdBu')
ax.axis('off')