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/.
- 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-pyh3_to_string - a numpy vectorized (
numpy.vectorize) variant ofh3-pyh3_to_string - the
cells_to_stringfunction 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.
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.
MIT