Skip to main content

Data science toolkit for the H3 geospatial grid

Project description

A data science toolkit for the H3 geospatial grid.

PyPI ReadTheDocs DOI

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 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:

---------------------------------------------------------------------------------------------- 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

h3ronpy-0.20.2.tar.gz (726.4 kB view hashes)

Uploaded Source

Built Distributions

h3ronpy-0.20.2-cp38-abi3-win_amd64.whl (1.6 MB view hashes)

Uploaded CPython 3.8+ Windows x86-64

h3ronpy-0.20.2-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB view hashes)

Uploaded CPython 3.8+ manylinux: glibc 2.17+ x86-64

h3ronpy-0.20.2-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.7 MB view hashes)

Uploaded CPython 3.8+ manylinux: glibc 2.17+ ARM64

h3ronpy-0.20.2-cp38-abi3-macosx_11_0_arm64.whl (1.6 MB view hashes)

Uploaded CPython 3.8+ macOS 11.0+ ARM64

h3ronpy-0.20.2-cp38-abi3-macosx_10_14_x86_64.whl (1.7 MB view hashes)

Uploaded CPython 3.8+ macOS 10.14+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page