Integrates H3 with GeoPandas and Pandas. image Binder image Documentation Status
⬢ Try it out ⬢
pip install h3pandas
conda-version Anaconda-Server Badge
conda install -c conda-forge h3pandas
h3pandas automatically applies H3 functions to both Pandas Dataframes and GeoPandas Geodataframes
# Prepare data >>> import pandas as pd >>> import h3pandas >>> df = pd.DataFrame({'lat': [50, 51], 'lng': [14, 15]})
>>> resolution = 10 >>> df = df.h3.geo_to_h3(resolution) >>> df | h3_10 | lat | lng | |:----------------|------:|------:| | 8a1e30973807fff | 50 | 14 | | 8a1e2659c2c7fff | 51 | 15 | >>> df = df.h3.h3_to_geo_boundary() >>> df | h3_10 | lat | lng | geometry | |:----------------|------:|------:|:----------------| | 8a1e30973807fff | 50 | 14 | POLYGON ((...)) | | 8a1e2659c2c7fff | 51 | 15 | POLYGON ((...)) |
h3pandas also provides some extended functionality out-of-the-box,
often simplifying common workflows into a single command.
# Set up data >>> import numpy as np >>> import pandas as pd >>> np.random.seed(1729) >>> df = pd.DataFrame({ >>> 'lat': np.random.uniform(50, 51, 100), >>> 'lng': np.random.uniform(14, 15, 100), >>> 'value': np.random.poisson(100, 100)}) >>> })
# Aggregate values by their location and sum >>> df = df.h3.geo_to_h3_aggregate(3) >>> df | h3_03 | value | geometry | |:----------------|--------:|:----------------| | 831e30fffffffff | 102 | POLYGON ((...)) | | 831e34fffffffff | 189 | POLYGON ((...)) | | 831e35fffffffff | 8744 | POLYGON ((...)) | | 831f1bfffffffff | 1040 | POLYGON ((...)) | # Aggregate to a lower H3 resolution >>> df.h3.h3_to_parent_aggregate(2) | h3_02 | value | geometry | |:----------------|--------:|:----------------| | 821e37fffffffff | 9035 | POLYGON ((...)) | | 821f1ffffffffff | 1040 | POLYGON ((...)) |
For more examples, see the example notebooks.
For a full API documentation and more usage examples, see the documentation.
H3-Pandas cover the basics of the H3 API, but there are still many possible improvements.
Any suggestions and contributions are very welcome!
In particular, the next steps are:
- Improvements & stability of the "Extended API", e.g.
k_ring_smoothing.
Additional possible directions
- Allow for alternate h3-py APIs such as memview_int
- Performance improvements through Cythonized h3-py
- Dask integration through dask-geopandas (experimental as of now)
See issues for more.