rHEALPixDGGS

Introduction

rHEALPixDGGS is a Python package that implements the rHEALPix Discrete Global Grid System (DGGS). rHEALPix stands for rearranged Hierarchical Equal Area isoLatitude Pixelization. HEALPix is an equal-area pixelization of the sphere from astronomy whose pixel centres lie on rings of constant latitude. rHEALPix rearranges its planar projection so that the globe unfolds into six equal squares.

The projection maps points between the ellipsoid and the plane. The grid system is built on top of it. Each square is divided into N_side × N_side equal children, and so on recursively, so every point on Earth lies in one cell at each resolution and all cells of a resolution have the same area. A cell is named by an identifier such as P40: a letter for its base square and one digit per level. Parents, children, neighbours and the topological relations between cells are computed from these identifiers. The projection is implemented in rhealpixdggs.pj_rhealpix; the grid system is rhealpixdggs.dggs.RHEALPixDGGS, with parameters N_side, the placement of the polar squares and the ellipsoid's central meridian.

Standards conformance

rHEALPixDGGS implements code to both define an rHEALPix DGGS Reference System and to perform topological queries on its identifiers. Our roadmap is for v1.0 to be fully compliant with OGC Topic 21 v2.0 / ISO 19170-1:2020. The requirement-by-requirement status is maintained in docs/source/conformance.rst.

Release Notes

This package was originally authored by Alexander Raichev in 2013 and is actively maintained. See CHANGES.rst for the release history, including explicit callouts of any breaking changes.

Error Budget

rHEALPix is a theoretically equal-area projection: all cells at a given resolution have the same area by construction. In practice, floating-point arithmetic introduces a small rounding error when computing cell areas. The RHEALPixDGGS.area_error_budget() method returns these values analytically for the default WGS84-based DGGS (WGS84_003, N_side=3, max_areal_resolution=1 m²):

The absolute tolerance answers the question: "how different can two computed cell areas be before we should conclude they are genuinely different, rather than just floating-point noise?" For example, at resolution 9 the tolerance is ~5 × 10⁻¹⁰ m² — if two cells' computed areas differ by less than half a nanometre squared, they should be treated as equal-area.

The relative tolerance is constant at 2.22 × 10⁻¹⁵ (10 × machine epsilon) for all resolutions, reflecting the fixed number of floating-point operations in the area formula. The absolute tolerance shrinks proportionally with cell area as resolution increases. Resolution 15 is the finest level supported by the default configuration (cells of approximately 0.41 m²).

Requirements

Dependencies are declared in pyproject.toml (this project is managed with Poetry; development dependencies are declared there too, under tool.poetry.group.dev.dependencies):

• NumPy >=2.0 Base N-dimensional array package
• SciPy >=1.11 Fundamental library for scientific computing
• Pyproj >=3.6 Python interface to the PROJ cartographic library
• Shapely >=2.1 Manipulation and analysis of planar GEOS geometries

Installation

This package is available on PyPI, the Python Package Index from where it can be installed as follows:

pip install rhealpixdggs

Spherical harmonic transforms on the grid (rhealpixdggs.harmonics) need ducc0, which the harmonics extra brings:

pip install "rhealpixdggs[harmonics]"

rHEALPixDGGS is also available for download from the GitHub repository https://github.com/manaakiwhenua/rhealpixdggs-py from where the latest version can be cloned.

You can install from source using Poetry in a virtual environment (MacOS and Linux, assuming Poetry is already installed on your system):

python3 -m venv rhealpixdggs
source rhealpixdggs/bin/activate
python -m pip install --upgrade pip
poetry install

Or on Windows:

python3 -m venv rhealpixdggs
rhealpixdggs\Scripts\activate
python -m pip install --upgrade pip
poetry install

For development:

poetry shell
poetry install

Tests

The files in the tests directory test the rHEALPixDGGS modules. These files are plain unittest files (the Python testing framework contained within the standard distribution), and the examples embedded in docstrings are tested with doctest (also part of the standard distribution).

Two UNIX shell scripts are included in this repository to run all unit and doc tests:

• scripts/run_doctests.sh
• scripts/run_unittests.sh

Running the command python tests/test_<foo>.py performs a sequence of automated tests of <foo>.py.

For example, tests/test_cell.py automatically tests cell.py.

If you update a module, then update its test file to test the changes you made!

Test early, test often, test automatically!

There are a couple of files in the main package directory that can be used to run all tests, starting run_....

Documentation

The manual for the current master branch is published at https://manaakiwhenua.github.io/rhealpixdggs-py/. It is built with Sphinx from docs/source and the package docstrings, and redeployed by the Docs workflow on every push to master.

To build it yourself, with Sphinx and the furo theme installed (both are in the dev dependency group), run make html from the docs directory, or make latexpdf for the PDF manual, which also needs LaTeX. The output lands in docs/build.

The system itself is described in The rHEALPix Discrete Global Grid System.

License

This code is dual-licensed. You may choose to use it under either:

• GNU Lesser General Public License v3.0 (see LICENSE-LGPL)
• MIT License (see LICENSE-MIT)

See the file LICENSE for more information about the dual licensing arrangement.

This dual licensing approach allows the software to be used in contexts where LGPL may not be permitted (such as certain corporate environments or standards bodies like the OGC) while still maintaining a copyleft option for those who prefer it.

Releasing

See RELEASING.md for the release process. Note that working with this repository's packaging (poetry install, poetry build, ...) requires Poetry version 2.0 or later.

A conda package rhealpixdggs is also maintained at conda-forge.

Contact

Maintainer:
Richard Law
Bioeconomy Science Institute
lawr@landcareresearch.co.nz

Release Manager:
Dr Nicholas J. Car
SURROUND Australia Pty Ltd
nicholas.car@surroundaustralia.com

Original author:
Alexander Raichev
https://raichev.net/
alex@raichev.net

Former Maintainer:
Robert Gibb
Manaaki Whenua – Landcare Research
gibbr@landcareresearch.co.nz