h3ronpy

A data science toolkit for the H3 geospatial grid <https://h3geo.org/>_.

.. image:: https://img.shields.io/pypi/v/h3ronpy :alt: PyPI :target: https://pypi.python.org/pypi/h3ronpy/

.. image:: https://readthedocs.org/projects/h3ronpy/badge/?version=latest :alt: ReadTheDocs :target: https://h3ronpy.readthedocs.io/

.. image:: https://zenodo.org/badge/402118389.svg :alt: DOI :target: https://zenodo.org/badge/latestdoi/402118389

This library is not a substitute for the official python h3 library <https://github.com/uber/h3-py>_ - 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 <https://github.com/HydroniumLabs/h3o>_ library.
• Build on Apache Arrow <https://arrow.apache.org>_ and pyarrow <https://arrow.apache.org/docs/python/index.html>_ for efficient data handling.
• Dedicated APIs for the the pandas <https://pandas.pydata.org>_ and polars <https://www.pola.rs/>_ dataframe libraries. The pandas support includes geopandas <https://geopandas.org>_.
• Multi-threaded conversion of raster data to the H3 grid using numpy arrays <https://numpy.org/>_.
• 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 of h3-py h3_to_string
• the cells_to_string function of this library (release build)

leads to the following result on a standard laptop:

.. code-block::

---------------------------------------------------------------------------------------------- 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 <https://pypi.org/project/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