API reference¶
-
class
h3pandas.h3pandas.H3Accessor(df: pandas.core.frame.DataFrame)[source]¶ Bases:
objectMethods
cell_area([unit])Adds the column h3_cell_area containing the area of each H3 address.
geo_to_h3(resolution[, lat_col, lng_col, …])Adds H3 index to (Geo)DataFrame.
geo_to_h3_aggregate(resolution[, operation, …])Adds H3 index to DataFrame, groups points with the same index and performs operation.
Adds the column h3_base_cell containing the base cell of each H3 address.
Adds the column h3_resolution containing the resolution of each H3 address.
Adds the column h3_is_valid containing the validity of each H3 address.
h3_to_center_child([resolution])Adds the column h3_center_child containing the center child of each H3 address.
Add geometry with centroid of each H3 address to the DataFrame.
Add geometry with H3 hexagons to the DataFrame.
h3_to_parent([resolution])Adds the column h3_{resolution} containing the parent of each H3 address.
h3_to_parent_aggregate(resolution[, …])Assigns parent cell to each row, groups by it and performs operation.
hex_ring([k, explode])Adds the column h3_hex_ring containing a list H3 addresses forming a hollow hexagonal ringat a distance k.
k_ring([k, explode])Adds the column h3_k_ring containing a list H3 addresses within a distance of k.
k_ring_smoothing([k, weights, return_geometry])Experimental.
polyfill(resolution[, explode])Adds the column h3_polyfill containing a list H3 addresses whose centroid falls into the Polygon.
polyfill_resample(resolution[, return_geometry])Experimental.
-
cell_area(unit: typing_extensions.Literal[km ^ 2, m ^ 2, rads ^ 2] = 'km^2') → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_cell_area containing the area of each H3 address. Assumes H3 index.
- Parameters
- unitstr, options: ‘km^2’, ‘m^2’, or ‘rads^2’
Unit for area result. Default: ‘km^2`
- Returns
- Geo(DataFrame) with h3_cell_area column added
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.cell_area() val h3_cell_area 881e309739fffff 5 0.695651 881e2659c3fffff 1 0.684242
-
geo_to_h3(resolution: int, lat_col: str = 'lat', lng_col: str = 'lng', set_index: bool = True) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds H3 index to (Geo)DataFrame.
pd.DataFrame: uses lat_col and lng_col (default lat and lng) gpd.GeoDataFrame: uses geometry
Assumes coordinates in epsg=4326.
- Parameters
- resolutionint
H3 resolution
- lat_colstr
Name of the latitude column (if used), default ‘lat’
- lng_colstr
Name of the longitude column (if used), default ‘lng’
- set_indexbool
If True, the columns with H3 addresses is set as index, default ‘True’
- Returns
- (Geo)DataFrame with H3 addresses added
See also
geo_to_h3_aggregateExtended API method that aggregates points by H3 address
Examples
>>> df = pd.DataFrame({'lat': [50, 51], 'lng':[14, 15]}) >>> df.h3.geo_to_h3(8) lat lng h3_08 881e309739fffff 50 14 881e2659c3fffff 51 15
>>> df.h3.geo_to_h3(8, set_index=False) lat lng h3_08 0 50 14 881e309739fffff 1 51 15 881e2659c3fffff
>>> gdf = gpd.GeoDataFrame({'val': [5, 1]}, >>> geometry=gpd.points_from_xy(x=[14, 15], y=(50, 51))) >>> gdf.h3.geo_to_h3(8) val geometry h3_08 881e309739fffff 5 POINT (14.00000 50.00000) 881e2659c3fffff 1 POINT (15.00000 51.00000)
-
geo_to_h3_aggregate(resolution: int, operation: Union[dict, str, Callable] = 'sum', lat_col: str = 'lat', lng_col: str = 'lng', return_geometry: bool = True) → pandas.core.frame.DataFrame[source]¶ Adds H3 index to DataFrame, groups points with the same index and performs operation.
pd.DataFrame: uses lat_col and lng_col (default lat and lng) gpd.GeoDataFrame: uses geometry
- Parameters
- resolutionint
H3 resolution
- operationUnion[dict, str, Callable]
Argument passed to DataFrame’s agg method, default ‘sum’
- lat_colstr
Name of the latitude column (if used), default ‘lat’
- lng_colstr
Name of the longitude column (if used), default ‘lng’
- return_geometry: bool
(Optional) Whether to add a geometry column with the hexagonal cells. Default = True
- Returns
- (Geo)DataFrame aggregated by H3 address into which each row’s point falls
See also
geo_to_h3H3 API method upon which this function builds
Examples
>>> df = pd.DataFrame({'lat': [50, 51], 'lng':[14, 15], 'val': [10, 1]}) >>> df.h3.geo_to_h3(1) lat lng val h3_01 811e3ffffffffff 50 14 10 811e3ffffffffff 51 15 1 >>> df.h3.geo_to_h3_aggregate(1) val geometry h3_01 811e3ffffffffff 11 POLYGON ((12.34575 50.55428, 12.67732 46.40696... >>> df = pd.DataFrame({'lat': [50, 51], 'lng':[14, 15], 'val': [10, 1]}) >>> df.h3.geo_to_h3_aggregate(1, operation='mean') val geometry h3_01 811e3ffffffffff 5.5 POLYGON ((12.34575 50.55428, 12.67732 46.40696... >>> df.h3.geo_to_h3_aggregate(1, return_geometry=False) val h3_01 811e3ffffffffff 11
-
h3_get_base_cell()[source]¶ Adds the column h3_base_cell containing the base cell of each H3 address. Assumes H3 index.
- Returns
- Geo(DataFrame) with h3_base_cell column added
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_get_base_cell() val h3_base_cell 881e309739fffff 5 15 881e2659c3fffff 1 15
-
h3_get_resolution() → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_resolution containing the resolution of each H3 address. Assumes H3 index.
- Returns
- Geo(DataFrame) with h3_resolution column added
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_get_resolution() val h3_resolution 881e309739fffff 5 8 881e2659c3fffff 1 8
-
h3_is_valid()[source]¶ Adds the column h3_is_valid containing the validity of each H3 address. Assumes H3 index.
- Returns
- Geo(DataFrame) with h3_is_valid column added
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, index=['881e309739fffff', 'INVALID']) >>> df.h3.h3_is_valid() val h3_is_valid 881e309739fffff 5 True INVALID 1 False
-
h3_to_center_child(resolution: int = None) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_center_child containing the center child of each H3 address. Assumes H3 index.
- Parameters
- resolutionint or None
H3 resolution. If none, then returns the child of resolution directly below that of each H3 cell
- Returns
- Geo(DataFrame) with h3_center_child column added
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_to_center_child() val h3_center_child 881e309739fffff 5 891e3097383ffff 881e2659c3fffff 1 891e2659c23ffff
-
h3_to_geo() → geopandas.geodataframe.GeoDataFrame[source]¶ Add geometry with centroid of each H3 address to the DataFrame. Assumes H3 index.
- Returns
- GeoDataFrame with Point geometry
- Raises
- ValueError
When an invalid H3 address is encountered
See also
h3_to_geo_boundaryAdds a hexagonal cell
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_to_geo() val geometry 881e309739fffff 5 POINT (14.00037 50.00055) 881e2659c3fffff 1 POINT (14.99715 51.00252)
-
h3_to_geo_boundary() → geopandas.geodataframe.GeoDataFrame[source]¶ Add geometry with H3 hexagons to the DataFrame. Assumes H3 index.
- Returns
- GeoDataFrame with H3 geometry
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_to_geo_boundary() val geometry 881e309739fffff 5 POLYGON ((13.99527 50.00368, 13.99310 49.99929... 881e2659c3fffff 1 POLYGON ((14.99201 51.00565, 14.98973 51.00133...
-
h3_to_parent(resolution: int = None) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_{resolution} containing the parent of each H3 address. Assumes H3 index.
- Parameters
- resolutionint or None
H3 resolution. If None, then returns the direct parent of each H3 cell.
- Returns
- Geo(DataFrame) with h3_{resolution} column added
- Raises
- ValueError
When an invalid H3 address is encountered
See also
h3_to_parent_aggregateExtended API method that aggregates cells by their parent cell
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_to_parent(5) val h3_05 881e309739fffff 5 851e3097fffffff 881e2659c3fffff 1 851e265bfffffff
-
h3_to_parent_aggregate(resolution: int, operation: Union[dict, str, Callable] = 'sum', return_geometry: bool = True) → geopandas.geodataframe.GeoDataFrame[source]¶ Assigns parent cell to each row, groups by it and performs operation. Assumes H3 index.
- Parameters
- resolutionint
H3 resolution
- operationUnion[dict, str, Callable]
Argument passed to DataFrame’s agg method, default ‘sum’
- return_geometry: bool
(Optional) Whether to add a geometry column with the hexagonal cells. Default = True
- Returns
- (Geo)DataFrame aggregated by the parent of each H3 address
- Raises
- ValueError
When an invalid H3 address is encountered
See also
h3_to_parentH3 API method upon which this function builds
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.h3_to_parent(1) val h3_01 881e309739fffff 5 811e3ffffffffff 881e2659c3fffff 1 811e3ffffffffff >>> df.h3.h3_to_parent_aggregate(1) val geometry h3_01 811e3ffffffffff 6 POLYGON ((12.34575 50.55428, 12.67732 46.40696... >>> df.h3.h3_to_parent_aggregate(1, operation='mean') val geometry h3_01 811e3ffffffffff 3 POLYGON ((12.34575 50.55428, 12.67732 46.40696... >>> df.h3.h3_to_parent_aggregate(1, return_geometry=False) val h3_01 811e3ffffffffff 6
-
hex_ring(k: int = 1, explode: bool = False) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_hex_ring containing a list H3 addresses forming a hollow hexagonal ringat a distance k. Assumes H3 index.
- Parameters
- kint
the distance from the origin H3 address. Default k = 1
- explodebool
If True, will explode the resulting list vertically. All other columns’ values are copied. Default: False
- Returns
- Geo(DataFrame) with h3_hex_ring column added
- Raises
- ValueError
When an invalid H3 address is encountered
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.hex_ring(1) val h3_hex_ring 881e309739fffff 5 [881e30973dfffff, 881e309703fffff, 881e309707f... 881e2659c3fffff 1 [881e2659ddfffff, 881e2659cbfffff, 881e2659d5f... >>> df.h3.hex_ring(1, explode=True) val h3_hex_ring 881e2659c3fffff 1 881e2659ddfffff 881e2659c3fffff 1 881e2659cbfffff 881e2659c3fffff 1 881e2659d5fffff 881e2659c3fffff 1 881e2659c7fffff 881e2659c3fffff 1 881e265989fffff 881e2659c3fffff 1 881e2659c1fffff 881e309739fffff 5 881e30973dfffff 881e309739fffff 5 881e309703fffff 881e309739fffff 5 881e309707fffff 881e309739fffff 5 881e30973bfffff 881e309739fffff 5 881e309715fffff 881e309739fffff 5 881e309731fffff
-
k_ring(k: int = 1, explode: bool = False) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_k_ring containing a list H3 addresses within a distance of k. Assumes H3 index.
- Parameters
- kint
the distance from the origin H3 address. Default k = 1
- explodebool
If True, will explode the resulting list vertically. All other columns’ values are copied. Default: False
- Returns
- Geo(DataFrame) with h3_k_ring column added
- Raises
- ValueError
When an invalid H3 address is encountered
See also
k_ring_smoothingExtended API method that distributes numeric values to the k-ring cells
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.k_ring(1) val h3_k_ring 881e309739fffff 5 [881e30973dfffff, 881e309703fffff, 881e309707f... 881e2659c3fffff 1 [881e2659ddfffff, 881e2659c3fffff, 881e2659cbf...
>>> df.h3.k_ring(1, explode=True) val h3_k_ring 881e2659c3fffff 1 881e2659ddfffff 881e2659c3fffff 1 881e2659c3fffff 881e2659c3fffff 1 881e2659cbfffff 881e2659c3fffff 1 881e2659d5fffff 881e2659c3fffff 1 881e2659c7fffff 881e2659c3fffff 1 881e265989fffff 881e2659c3fffff 1 881e2659c1fffff 881e309739fffff 5 881e30973dfffff 881e309739fffff 5 881e309703fffff 881e309739fffff 5 881e309707fffff 881e309739fffff 5 881e30973bfffff 881e309739fffff 5 881e309715fffff 881e309739fffff 5 881e309739fffff 881e309739fffff 5 881e309731fffff
-
k_ring_smoothing(k: Optional[int] = None, weights: Optional[Sequence[float]] = None, return_geometry: bool = True) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Experimental. Creates a k-ring around each input cell and distributes the cell’s values.
- The values are distributed either
uniformly (by setting k) or
by weighing their values using weights.
Only numeric columns are modified.
- Parameters
- kint
The distance from the origin H3 address
- weightsSequence[float]
Weighting of the values based on the distance from the origin. First weight corresponds to the origin. Values are be normalized to add up to 1.
- return_geometry: bool
(Optional) Whether to add a geometry column with the hexagonal cells. Default = True
- Returns
- (Geo)DataFrame with smoothed values
See also
k_ringH3 API method upon which this method builds
Examples
>>> df = pd.DataFrame({'val': [5, 1]}, >>> index=['881e309739fffff', '881e2659c3fffff']) >>> df.h3.k_ring_smoothing(1) val geometry h3_k_ring 881e265989fffff 0.142857 POLYGON ((14.99488 50.99821, 14.99260 50.99389... 881e2659c1fffff 0.142857 POLYGON ((14.97944 51.00758, 14.97717 51.00326... 881e2659c3fffff 0.142857 POLYGON ((14.99201 51.00565, 14.98973 51.00133... 881e2659c7fffff 0.142857 POLYGON ((14.98231 51.00014, 14.98004 50.99582... 881e2659cbfffff 0.142857 POLYGON ((14.98914 51.01308, 14.98687 51.00877... 881e2659d5fffff 0.142857 POLYGON ((15.00458 51.00371, 15.00230 50.99940... 881e2659ddfffff 0.142857 POLYGON ((15.00171 51.01115, 14.99943 51.00684... 881e309703fffff 0.714286 POLYGON ((13.99235 50.01119, 13.99017 50.00681... 881e309707fffff 0.714286 POLYGON ((13.98290 50.00555, 13.98072 50.00116... 881e309715fffff 0.714286 POLYGON ((14.00473 50.00932, 14.00255 50.00494... 881e309731fffff 0.714286 POLYGON ((13.99819 49.99617, 13.99602 49.99178... 881e309739fffff 0.714286 POLYGON ((13.99527 50.00368, 13.99310 49.99929... 881e30973bfffff 0.714286 POLYGON ((14.00765 50.00181, 14.00547 49.99742... 881e30973dfffff 0.714286 POLYGON ((13.98582 49.99803, 13.98364 49.99365... >>> df.h3.k_ring_smoothing(weights=[2, 1]) val geometry h3_hex_ring 881e265989fffff 0.125 POLYGON ((14.99488 50.99821, 14.99260 50.99389... 881e2659c1fffff 0.125 POLYGON ((14.97944 51.00758, 14.97717 51.00326... 881e2659c3fffff 0.250 POLYGON ((14.99201 51.00565, 14.98973 51.00133... 881e2659c7fffff 0.125 POLYGON ((14.98231 51.00014, 14.98004 50.99582... 881e2659cbfffff 0.125 POLYGON ((14.98914 51.01308, 14.98687 51.00877... 881e2659d5fffff 0.125 POLYGON ((15.00458 51.00371, 15.00230 50.99940... 881e2659ddfffff 0.125 POLYGON ((15.00171 51.01115, 14.99943 51.00684... 881e309703fffff 0.625 POLYGON ((13.99235 50.01119, 13.99017 50.00681... 881e309707fffff 0.625 POLYGON ((13.98290 50.00555, 13.98072 50.00116... 881e309715fffff 0.625 POLYGON ((14.00473 50.00932, 14.00255 50.00494... 881e309731fffff 0.625 POLYGON ((13.99819 49.99617, 13.99602 49.99178... 881e309739fffff 1.250 POLYGON ((13.99527 50.00368, 13.99310 49.99929... 881e30973bfffff 0.625 POLYGON ((14.00765 50.00181, 14.00547 49.99742... 881e30973dfffff 0.625 POLYGON ((13.98582 49.99803, 13.98364 49.99365... >>> df.h3.k_ring_smoothing(1, return_geometry=False) val h3_k_ring 881e265989fffff 0.142857 881e2659c1fffff 0.142857 881e2659c3fffff 0.142857 881e2659c7fffff 0.142857 881e2659cbfffff 0.142857 881e2659d5fffff 0.142857 881e2659ddfffff 0.142857 881e309703fffff 0.714286 881e309707fffff 0.714286 881e309715fffff 0.714286 881e309731fffff 0.714286 881e309739fffff 0.714286 881e30973bfffff 0.714286 881e30973dfffff 0.714286
-
polyfill(resolution: int, explode: bool = False) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Adds the column h3_polyfill containing a list H3 addresses whose centroid falls into the Polygon. Assumes H3 index.
- Parameters
- resolutionint
H3 resolution
- explodebool
If True, will explode the resulting list vertically. All other columns’ values are copied. Default: False
- Returns
- Geo(DataFrame) with h3_polyfill column added
- Raises
- ValueError
When an invalid H3 address is encountered
See also
polyfill_resampleExtended API method that distributes the polygon’s values to the H3 cells contained in it
Examples
>>> from shapely.geometry import box >>> gdf = gpd.GeoDataFrame(geometry=[box(0, 0, 1, 1)]) >>> gdf.h3.polyfill(4) geometry h3_polyfill 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... [84754e3ffffffff, 84754c7ffffffff, 84754c5ffff... # noqa E501 >>> gdf.h3.polyfill(4, explode=True) geometry h3_polyfill 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754e3ffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754c7ffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754c5ffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754ebffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754edffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754e1ffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 84754e9ffffffff 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... 8475413ffffffff
-
polyfill_resample(resolution: int, return_geometry: bool = True) → Union[pandas.core.frame.DataFrame, geopandas.geodataframe.GeoDataFrame][source]¶ Experimental. Currently essentially polyfill(…, explode=True) that sets the H3 index and adds the H3 cell geometry.
- Parameters
- resolutionint
H3 resolution
- return_geometry: bool
(Optional) Whether to add a geometry column with the hexagonal cells. Default = True
- Returns
- (Geo)DataFrame with H3 cells with centroids within the input polygons.
See also
polyfillH3 API method upon which this method builds
Examples
>>> from shapely.geometry import box >>> gdf = gpd.GeoDataFrame(geometry=[box(0, 0, 1, 1)]) >>> gdf.h3.polyfill_resample(4) index geometry h3_polyfill 84754e3ffffffff 0 POLYGON ((0.33404 -0.11975, 0.42911 0.07901, 0... 84754c7ffffffff 0 POLYGON ((0.92140 -0.03115, 1.01693 0.16862, 0... 84754c5ffffffff 0 POLYGON ((0.91569 0.33807, 1.01106 0.53747, 0.... 84754ebffffffff 0 POLYGON ((0.62438 0.10878, 0.71960 0.30787, 0.... 84754edffffffff 0 POLYGON ((0.32478 0.61394, 0.41951 0.81195, 0.... 84754e1ffffffff 0 POLYGON ((0.32940 0.24775, 0.42430 0.44615, 0.... 84754e9ffffffff 0 POLYGON ((0.61922 0.47649, 0.71427 0.67520, 0.... 8475413ffffffff 0 POLYGON ((0.91001 0.70597, 1.00521 0.90497, 0....
-