README.md

 

H3-Pandas ⬢ 🐼

Integrates H3 with GeoPandas and Pandas.

 

---

⬢ Try it out ⬢

---

Installation

pip

pip install h3pandas

conda

conda install -c conda-forge h3pandas

Usage examples

H3 API

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 ((...)) |

H3-Pandas Extended API

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 ((...)) |

Further examples

For more examples, see the example notebooks.

API

For a full API documentation and more usage examples, see the documentation.

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
• Performance improvements through Cythonized h3-py
• Dask integration through dask-geopandas (experimental as of now)

See issues for more.