dggrid4py - a Python library to run highlevel functions of DGGRID

GitHub

GNU AFFERO GENERAL PUBLIC LICENSE

DGGRID is a free software program for creating and manipulating Discrete Global Grids created and maintained by Kevin Sahr. DGGRID version 8.34 was released 13. November 2024

• DGGRID Version 8.3 on GitHub
• DGGRID User Manual

You need the ddgrid tool compiled available on the system.

Besides some lowlevel access influence the dggrid operations' metafile creation, a few highlevel functions are integrated to work with the more comfortable geopython libraries, like shapely and geopandas

• gridcellpolygonsforextent(): fill extent/subset with cells at resolution (clip or world)
• gridcellpolygonsfromcellids(): geometryfromcellid for dggs at resolution (from id list)
• gridcellidsforextent(): getallindexes/cellids for dggs at resolution (clip or world)
• cellsforgeopoints(): polyoutline for point/centre at resolution
• addresstransform(): conversion betwenn cellid address types, like SEQNUM, Z7, or Q2DI

```python import geopandas import shapely

from dggrid4py import DGGRIDv7

create an inital instance that knows where the dggrid tool lives, configure temp workspace and log/stdout output

if you have

dggridinstance = DGGRIDv7(executable='<pathto>/dggrid', workingdir='.', capturelogs=False, silent=False, tmpgeoout_legacy=False, debug=False)

global ISEA4T grid at resolution 5 into GeoDataFrame to Shapefile

gdf1 = dggridinstance.gridcellpolygonsforextent('ISEA4T', 5) print(gdf1.head()) gdf1.tofile('isea4t_5.shp')

gdfcentroids = dggridinstance.gridcellcentroidsforextent(dggstype='ISEA7H', resolution=4, mixedaperturelevel=None, clipgeom=None)

clip extent

clip_bound = shapely.geometry.box(20.2,57.00, 28.4,60.0 )

ISEA7H grid at resolution 9, for extent of provided WGS84 rectangle into GeoDataFrame to Shapefile

gdf3 = dggridinstance.gridcellpolygonsforextent('ISEA7H', 9, clipgeom=estbound) print(gdf3.head()) gdf3.tofile('grids/estshapeisea7h_9.shp')

generate cell and areal statistics for a ISEA7H grids from resolution 0 to 8 (return a pandas DataFrame)

df1 = dggridinstance.gridstatstable('ISEA7H', 8) print(df1.head(8)) df1.tocsv('isea7h8stats.csv', index=False)

generate the DGGS grid cells that would cover a GeoDataFrame of points, return Polygons with cell IDs as GeoDataFrame

gdf4 = dggridinstance.cellsforgeopoints(geodfpointswgs84, False, 'ISEA7H', 5) print(gdf4.head()) gdf4.tofile('polycellsfrompointsisea7h_5.shp')

generate the DGGS grid cells that would cover a GeoDataFrame of points, return cell IDs added as column to the points GDF

gdf5 = dggridinstance.cellsforgeopoints(geodfpointswgs84=geodfpointswgs84, cellidsonly=True, dggstype='ISEA4H', resolution=8) print(gdf5.head()) gdf5.tofile('geopointcellidsfrompointsisea4h_8.shp')

generate DGGS grid cell polygons based on 'cellidlist' (a list or np.array of provided cell_ids)

gdf6 = dggridinstance.gridcellpolygonsfromcellids(cellidlist=[1, 4, 8], 'ISEA7H', 5) print(gdf6.head()) gdf6.tofile('fromseqnumsisea7h_5.shp')

v0.2.6 API update split at dateline for cartesian GIS tools

gdf7 = dggridinstance.gridcellpolygonsforextent('ISEA7H', 3, splitdateline=True) gdf7.tofile('globalisea7h3interrupted.shp')

gdfz1 = dggridinstance.gridcellpolygonsforextent('IGEO7', 5, clipgeom=estbound, outputaddresstype='Z7STRING') print(gdfz1.head(3))

dfz1 = dggridinstance.guesszstrresolution(gdfz1['name'].values, 'IGEO7', inputaddresstype='Z7STRING') print(df_z1.head(3))

dfq2di = dggridinstance.addresstransform(gdfz1['name'].values, 'IGEO7', 5, inputaddresstype='Z7STRING', outputaddresstype='Q2DI') print(dfq2di.head(3))

dftri = dggridinstance.addresstransform(gdfz1['name'].values, 'IGEO7', 5, inputaddresstype='Z7STRING', outputaddresstype='PROJTRI') print(dftri.head(3))

```

Portable DGGRID binary

if you don't have a special local distribution of the dggrid-tool or if you didn't install with conda-forge, you can use a provided portable:

```python

from dggrid4py import tool

dggridexec = tool.getportableexecutable(".") dggridinstanceportable = DGGRIDv7(executable=dggridexec, workingdir='.', capturelogs=False, silent=True, hasgdal=False, tmpgeooutlegacy=True, debug=False)

```

TODO:

• get parentforcell_id at coarser resolution
• get childrenforcell_id at finer resolution

Remark: This is now possible with the IGEO7/Z7 system.

Related work:

Originally insprired by dggridR, Richard Barnes’ R interface to DGGRID. However, dggridR is directly linked via Rcpp to DGGRID and calls native C/C++ functions.

After some unsuccessful trials with ctypes, cython, CFFI, pybind11 or cppyy (rather due to lack of experience) I found am2222/pydggrid (on PyPI) which made apparently some initial scaffolding for the transform operation with pybind11 including some sophisticated conda packaging for Windows. This might be worth following up. Interestingly, its todos include "Adding GDAL export Geometry Support" and "Support GridGeneration using DGGRID" which this dggrid4py module supports with integration of GeoPandas.

Bundling for different operating systems

Having to compile DGGRID for Windows can be a bit challenging. We are working on an updated conda package. Currently DGGRID v8.3 is available on conda-forge:

greater context DGGS in Earth Sciences and GIS

Some reading to be excited about: discourse.pangeo.io