h3ronpy
A data science toolkit for the H3 geospatial grid.
This library is not a substitute for the official python h3 library - instead it provides more high-level functions on top of H3 and integrations into common dataframe libraries.
Documentation is available on https://h3ronpy.readthedocs.io/.
Features
H3 algorithms provided using the performant h3o library.
Build on Apache Arrow and pyarrow for efficient data handling.
Dedicated APIs for the the pandas and polars dataframe libraries. The pandas support includes geopandas.
Multi-threaded conversion of raster data to the H3 grid using numpy arrays.
Multi-threaded conversion of vector data, including geopandas GeoDataFrames and any object which supports the python __geo_interface__ protocol (shapely, geojson, …).
Most parts of this library aim to be well-performing. Benchmarking the conversion of 1000 uint64 cell values to strings using
a simplistic list comprehension calling
h3-py
h3_to_string
a numpy vectorized (
numpy.vectorize
) variant ofh3-py
h3_to_string
the
cells_to_string
function of this library (release build)
leads to the following result on a standard laptop:
---------------------------------------------------------------------------------------------- benchmark: 3 tests ---------------------------------------------------------------------------------------------
Name (time in us) Min Max Mean StdDev Median IQR Outliers OPS (Kops/s) Rounds Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_cells_to_string 48.4710 (1.0) 75.5000 (1.0) 52.4252 (1.0) 1.5461 (1.0) 52.0330 (1.0) 0.4890 (1.0) 307;448 19.0748 (1.0) 4090 1
test_h3_to_string_python_list 290.5460 (5.99) 325.8180 (4.32) 297.5644 (5.68) 4.8769 (3.15) 296.1350 (5.69) 8.2420 (16.85) 806;4 3.3606 (0.18) 2863 1
test_h3_to_string_numpy_vectorized 352.9870 (7.28) 393.8450 (5.22) 360.1159 (6.87) 3.7195 (2.41) 359.4820 (6.91) 3.8420 (7.86) 447;131 2.7769 (0.15) 2334 1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Legend:
Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
OPS: Operations Per Second, computed as 1 / Mean
The benchmark implementation can be found in tests/polars/test_benches.py
and uses pytest-benchmark.
Limitations
Not all functionalities of the H3 grid are wrapped by this library, the current feature-set was implemented when there was a need and the time for it. As a opensource library new features can be requested in the form of github issues or contributed using pull requests.
License
MIT
Note
This project is under active development.
Contents
- Installation
- Usage examples
- API documentation
- Changelog
- Unreleased
- 0.20.2 - 2024-04-16
- 0.20.1 - 2024-03-01
- 0.20.0 - 2024-02-03
- 0.19.2 - 2023-11-16
- 0.19.1 - 2023-10-18
- 0.19.0 - 2023-10-11
- 0.18.0 - 2023-08-31
- 0.17.5 - 2023-08-22
- 0.17.4 - 2023-07-28
- 0.17.3 - 2023-07-27
- 0.17.2 - 2023-07-13
- 0.17.1 - 2023-07-06
- 0.17.0 - 2023-06-27
- 0.16.1 - 2023-02-16
- 0.16.0 - 2022-12-28
- 0.15.1 - 2022-10-28
- 0.15.0 - 2022-09-11
- 0.14.0 - 2022-01-29
- 0.13.1 - 2021-12-13
- 0.13.0 - 2021-12-10
- 0.12.0 - 2021-08-10
- 0.11.0 - 2021-06-12
- 0.10.0 - 2021-04-24
- 0.9.0 - 2021-04-11
- Earlier versions
- License
- Contributing