Skip to main content

a Python library to run highlevel functions of DGGRIDv7 and v8

Project description

dggrid4py - a Python library to run highlevel functions of DGGRID

PyPI version DOI Documentation Status GitHub

Population Gridded

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

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

  • grid_cell_polygons_for_extent(): fill extent/subset with cells at resolution (clip or world)
  • grid_cell_polygons_from_cellids(): geometry_from_cellid for dggs at resolution (from id list)
  • grid_cellids_for_extent(): get_all_indexes/cell_ids for dggs at resolution (clip or world)
  • cells_for_geo_points(): poly_outline for point/centre at resolution
  • address_transform(): conversion betwenn cell_id address types, like SEQNUM, Z7, or Q2DI
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
dggrid_instance = DGGRIDv7(executable='<path_to>/dggrid', working_dir='.', capture_logs=False, silent=False, tmp_geo_out_legacy=False, debug=False)


# global ISEA4T grid at resolution 5 into GeoDataFrame to Shapefile
gdf1 = dggrid_instance.grid_cell_polygons_for_extent('ISEA4T', 5)
print(gdf1.head())
gdf1.to_file('isea4t_5.shp')

gdf_centroids = dggrid_instance.grid_cell_centroids_for_extent(dggs_type='ISEA7H', resolution=4, mixed_aperture_level=None, clip_geom=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 = dggrid_instance.grid_cell_polygons_for_extent('ISEA7H', 9, clip_geom=est_bound)
print(gdf3.head())
gdf3.to_file('grids/est_shape_isea7h_9.shp')

# generate cell and areal statistics for a ISEA7H grids from resolution 0 to 8 (return a pandas DataFrame)
df1 = dggrid_instance.grid_stats_table('ISEA7H', 8)
print(df1.head(8))
df1.to_csv('isea7h_8_stats.csv', index=False)

# generate the DGGS grid cells that would cover a GeoDataFrame of points, return Polygons with cell IDs as GeoDataFrame
gdf4 = dggrid_instance.cells_for_geo_points(geodf_points_wgs84, False, 'ISEA7H', 5)
print(gdf4.head())
gdf4.to_file('polycells_from_points_isea7h_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 = dggrid_instance.cells_for_geo_points(geodf_points_wgs84=geodf_points_wgs84, cell_ids_only=True, dggs_type='ISEA4H', resolution=8)
print(gdf5.head())
gdf5.to_file('geopoint_cellids_from_points_isea4h_8.shp')

# generate DGGS grid cell polygons based on 'cell_id_list' (a list or np.array of provided cell_ids)
gdf6 = dggrid_instance.grid_cell_polygons_from_cellids(cell_id_list=[1, 4, 8], 'ISEA7H', 5)
print(gdf6.head())
gdf6.to_file('from_seqnums_isea7h_5.shp')

# v0.2.6 API update split at dateline for cartesian GIS tools
gdf7 = dggrid_instance.grid_cell_polygons_for_extent('ISEA7H', 3, split_dateline=True)
gdf7.to_file('global_isea7h_3_interrupted.shp')

gdf_z1 = dggrid_instance.grid_cell_polygons_for_extent('IGEO7', 5, clip_geom=est_bound, output_address_type='Z7_STRING')
print(gdf_z1.head(3))

df_z1 = dggrid_instance.guess_zstr_resolution(gdf_z1['name'].values, 'IGEO7', input_address_type='Z7_STRING')
print(df_z1.head(3))

df_q2di = dggrid_instance.address_transform(gdf_z1['name'].values, 'IGEO7', 5, input_address_type='Z7_STRING', output_address_type='Q2DI')
print(df_q2di.head(3))

df_tri = dggrid_instance.address_transform(gdf_z1['name'].values, 'IGEO7', 5, input_address_type='Z7_STRING', output_address_type='PROJTRI')
print(df_tri.head(3))

TODO:

  • get parent_for_cell_id at coarser resolution
  • get children_for_cell_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:

Latest version on conda-forge

greater context DGGS in Earth Sciences and GIS

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

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

dggrid4py-0.4.1.tar.gz (35.7 kB view details)

Uploaded Source

Built Distribution

dggrid4py-0.4.1-py3-none-any.whl (35.9 kB view details)

Uploaded Python 3

File details

Details for the file dggrid4py-0.4.1.tar.gz.

File metadata

  • Download URL: dggrid4py-0.4.1.tar.gz
  • Upload date:
  • Size: 35.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for dggrid4py-0.4.1.tar.gz
Algorithm Hash digest
SHA256 253f45e436db39fc251f2068b9d2ae87bdc18de8a9535f4dbe6c4cd19addaf7e
MD5 5dfb7a0e0a0a76697dc43e7db87d8d79
BLAKE2b-256 e2e4609ced6561fee8befba4ab1f87a3967da389ea8b785a1f84a06bf80560bd

See more details on using hashes here.

File details

Details for the file dggrid4py-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: dggrid4py-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 35.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for dggrid4py-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 483e51b9464c23c871ebc18eab14d2e51b36f997da3e47824648eab9eb5ce68d
MD5 4e11d157a1ffd6c74cec882ee40aa3b3
BLAKE2b-256 64a3b68229447e0223fa3c42e2f430f1b1ea8087019fdb26b2fc52b332aa609f

See more details on using hashes here.

Supported by

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