This library contains classes for representing DGGS Cells and collections of these ("CellCollection") according to parametrisations of the rHEALPix Discrete Global Grid System. This provides a convenient low level API to work with Cells and CellCollections. An example of a library that utilises these objects for higher level geospatial operations is the rhealpix-sf library which provides a set of Simple Feature relation operations for DGGS Cells.
Validation is provided for Cell and CellCollections. CellCollections have the following operations performed on instantiation:
- compression (where all children of a parent are present, replace with their parent)
- deduplication (removal of repeated cells)
- absorb (where a child and its parent are present, remove the child/children)
- ordering (alphabetical and numerical based on suids)
These operations provide a consistent representation of collections of Cells, allowing higher level operations to work with a simplified, valid, and consistent set of cells.
Cells and CellCollections have the following attributes or methods:
- add: Add two sets of Cell or CellCollections, returning a CellCollection
- subtract: Subtract a Cell or CellCollection from an other, returning a CellCollection
- equal: Test two Cells or CellCollections for equivalence
- len: the number of Cells in a Cell (1) or CellCollection (N)
- area: to be implemented
- resolution / min and max resolution for CellCollections: the resolution or minimum / maximum resolution for Cells or CellCollections respectively.
- neighbours: the Cells immediately neighbouring a Cell or CellCollection, optionally including diagonals. For CellCollections, excludes neighbouring cells interior to the CellCollection. Resolution specifiable.
- border: the set of interior Cells along the edges of a Cell or CellCollection. Resolution specifiable.
- children: the set of child Cells for a Cell or CellCollection. Resolution specifiable.
Install from PyPi, for example using pip or poetry.
https://pypi.org/project/rhealpix-geo/
This package has no dependencies.
These functions are implemented in the file rheal/dggs_classes.py
This means they can be used like this (full working script):
from rheal import Cell, CellCollection
a = Cell("R1")
b = Cell("R11")
c = CellCollection("R1 R2")
print(a + b)
# b is within a, so a CellCollection equivalent to a is returned
print(a - b)
# b is within a, so a subset of a is returned
print(a + c)
# c contains a, so a CellCollection equivalent to c is returned
print(a == b)
# a's border at a resolution two levels higher than a's resolution
print(a.border(a.resolution+2))
# a's children at a resolution one level higher (default) than a's resolution
print(a.children())
# a's neighbours at a's resolution (default) including diagonals (default). Note only 7 neighbours due to the shape of the north hemisphere cell.
print(a.neighbours())All tests are in tests/ and implemented using pytest.
There are individual tests for each of the Cell and CellCollection operations.
Via GitHub, Issues & Pull Requests:
This code is licensed with the BSD 3-clause license as per LICENSE.
@software{https://github.com/surroundaustralia/rhealpix-geo,
author = {{David Habgood}},
title = {Objects for DGGS Cells and collections of Cells},
version = {0.0.1},
date = {2021},
url = {https://github.com/surroundaustralia/rhealpix-geo}
}Creator & maintainer:
David Habgood
Application Architect
SURROUND Australia Pty Ltd
david.habgood@surroundaustrlaia.com