https://github.com/DahnJ/H3-Pandas
Integration of H3 with GeoPandas and Pandas
https://github.com/DahnJ/H3-Pandas
geopandas geospatial h3 h3-pandas hexagons-are-bestagons pandas pyhon
Last synced: over 1 year ago
JSON representation
Integration of H3 with GeoPandas and Pandas
- Host: GitHub
- URL: https://github.com/DahnJ/H3-Pandas
- Owner: DahnJ
- License: mit
- Created: 2021-05-22T09:26:44.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-02T01:25:02.000Z (over 1 year ago)
- Last Synced: 2025-03-02T01:27:08.809Z (over 1 year ago)
- Topics: geopandas, geospatial, h3, h3-pandas, hexagons-are-bestagons, pandas, pyhon
- Language: Jupyter Notebook
- Homepage: http://h3-pandas.readthedocs.io/
- Size: 12.3 MB
- Stars: 210
- Watchers: 5
- Forks: 20
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# H3-Pandas ⬢ 🐼
Integrates [H3](https://github.com/uber/h3-py) with [GeoPandas](https://github.com/geopandas/geopandas)
and [Pandas](https://github.com/pandas-dev/pandas).
[](https://colab.research.google.com/github/DahnJ/H3-Pandas/blob/master/notebook/00-intro.ipynb)
[](https://mybinder.org/v2/gh/DahnJ/H3-Pandas/HEAD?filepath=%2Fnotebook%2F00-intro.ipynb)
[](https://opensource.org/licenses/MIT)
[](https://pip.pypa.io/en/stable/?badge=stable)
---
⬢ Try it out ⬢
---
## Installation
### pip
[](https://pypi.python.org/pypi/h3pandas)
```bash
pip install h3pandas
```
### conda
[]()
[](https://anaconda.org/conda-forge/h3pandas)
```bash
conda install -c conda-forge h3pandas
```
## Usage examples
### H3 API
`h3pandas` automatically applies H3 functions to both Pandas Dataframes and GeoPandas Geodataframes
```python
# Prepare data
>>> import pandas as pd
>>> import h3pandas
>>> df = pd.DataFrame({'lat': [50, 51], 'lng': [14, 15]})
```
```python
>>> 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 ((...)) |
```
### H3-Pandas Extended API
`h3pandas` also provides some extended functionality out-of-the-box,
often simplifying common workflows into a single command.
```python
# 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)})
>>> })
```
```python
# 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 ((...)) |
```
### Further examples
For more examples, see the
[example notebooks](https://nbviewer.jupyter.org/github/DahnJ/H3-Pandas/tree/master/notebook/).
## API
For a full API documentation and more usage examples, see the
[documentation](https://h3-pandas.readthedocs.io/en/latest/).
## Development
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](https://github.com/uber/h3-py#h3apimemview_int)
- [ ] Performance improvements through [Cythonized h3-py](https://github.com/uber/h3-py/pull/147)
- [ ] [Dask](https://github.com/dask/dask) integration through [dask-geopandas](https://github.com/geopandas/dask-geopandas) (experimental as of now)
See [issues](https://github.com/DahnJ/H3-Pandas/issues) for more.