# dggrid4py - a Python library to run highlevel functions of DGGRID
[](https://badge.fury.io/py/dggrid4py) [](https://zenodo.org/badge/latestdoi/295495597) [](https://dggrid4py.readthedocs.io/en/latest/?badge=latest)
[](https://twitter.com/allixender/status/1324055326111485959)
GNU AFFERO GENERAL PUBLIC LICENSE
[DGGRID](https://www.discreteglobalgrids.org/software/) is a free software program for creating and manipulating Discrete Global Grids created and maintained by Kevin Sahr. DGGRID version 8.1b was released 12. January 2024
- [DGGRID Version 8.1b on GitHub](https://github.com/sahrk/DGGRID)
- [DGGRID User Manual](https://github.com/sahrk/DGGRID/blob/d08e10d761f7bedd72a253ab1057458f339de51e/dggridManualV81b.pdf)
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
```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
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
## Related work:
Originally insprired by [dggridR](https://github.com/r-barnes/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](https://github.com/am2222/pydggrid) ([on PyPI](https://pypi.org/project/pydggrid/)) which made apparently some initial scaffolding for the transform operation with [pybind11](https://pybind11.readthedocs.io/en/master/) 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 v7.8 is available on conda-forge:
[](https://anaconda.org/conda-forge/dggrid)
## greater context DGGS in Earth Sciences and GIS
Some reading to be excited about: [discourse.pangeo.io](https://discourse.pangeo.io/t/discrete-global-grid-systems-dggs-use-with-pangeo/2274)
Raw data
{
"_id": null,
"home_page": "https://github.com/allixender/dggrid4py",
"name": "dggrid4py",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8",
"maintainer_email": null,
"keywords": "python, GIS, DGGS, DGGRID, hexagons, grids, spatial statistics",
"author": "Alexander Kmoch",
"author_email": "alexander.kmoch@ut.ee",
"download_url": "https://files.pythonhosted.org/packages/4e/2a/cbf3559f11be497ce5bb69c9d225b2a30987a37b6b84e4982359124fb9db/dggrid4py-0.3.0.tar.gz",
"platform": null,
"description": "# dggrid4py - a Python library to run highlevel functions of DGGRID\n\n[](https://badge.fury.io/py/dggrid4py) [](https://zenodo.org/badge/latestdoi/295495597) [](https://dggrid4py.readthedocs.io/en/latest/?badge=latest)\n\n[](https://twitter.com/allixender/status/1324055326111485959)\n\nGNU AFFERO GENERAL PUBLIC LICENSE\n\n[DGGRID](https://www.discreteglobalgrids.org/software/) is a free software program for creating and manipulating Discrete Global Grids created and maintained by Kevin Sahr. DGGRID version 8.1b was released 12. January 2024\n\n- [DGGRID Version 8.1b on GitHub](https://github.com/sahrk/DGGRID)\n- [DGGRID User Manual](https://github.com/sahrk/DGGRID/blob/d08e10d761f7bedd72a253ab1057458f339de51e/dggridManualV81b.pdf)\n\nYou need the ddgrid tool compiled available on the system.\n\nBesides 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\n\n- grid_cell_polygons_for_extent(): fill extent/subset with cells at resolution (clip or world)\n- grid_cell_polygons_from_cellids(): geometry_from_cellid for dggs at resolution (from id list)\n- grid_cellids_for_extent(): get_all_indexes/cell_ids for dggs at resolution (clip or world)\n- cells_for_geo_points(): poly_outline for point/centre at resolution\n\n\n```python\nimport geopandas\nimport shapely\n\nfrom dggrid4py import DGGRIDv7\n\n# create an inital instance that knows where the dggrid tool lives, configure temp workspace and log/stdout output\ndggrid_instance = DGGRIDv7(executable='<path_to>/dggrid', working_dir='.', capture_logs=False, silent=False, tmp_geo_out_legacy=False, debug=False)\n\n\n# global ISEA4T grid at resolution 5 into GeoDataFrame to Shapefile\ngdf1 = dggrid_instance.grid_cell_polygons_for_extent('ISEA4T', 5)\nprint(gdf1.head())\ngdf1.to_file('isea4t_5.shp')\n\ngdf_centroids = dggrid_instance.grid_cell_centroids_for_extent(dggs_type='ISEA7H', resolution=4, mixed_aperture_level=None, clip_geom=None)\n\n# clip extent\nclip_bound = shapely.geometry.box(20.2,57.00, 28.4,60.0 )\n\n# ISEA7H grid at resolution 9, for extent of provided WGS84 rectangle into GeoDataFrame to Shapefile\ngdf3 = dggrid_instance.grid_cell_polygons_for_extent('ISEA7H', 9, clip_geom=est_bound)\nprint(gdf3.head())\ngdf3.to_file('grids/est_shape_isea7h_9.shp')\n\n# generate cell and areal statistics for a ISEA7H grids from resolution 0 to 8 (return a pandas DataFrame)\ndf1 = dggrid_instance.grid_stats_table('ISEA7H', 8)\nprint(df1.head(8))\ndf1.to_csv('isea7h_8_stats.csv', index=False)\n\n# generate the DGGS grid cells that would cover a GeoDataFrame of points, return Polygons with cell IDs as GeoDataFrame\ngdf4 = dggrid_instance.cells_for_geo_points(geodf_points_wgs84, False, 'ISEA7H', 5)\nprint(gdf4.head())\ngdf4.to_file('polycells_from_points_isea7h_5.shp')\n\n# generate the DGGS grid cells that would cover a GeoDataFrame of points, return cell IDs added as column to the points GDF\ngdf5 = dggrid_instance.cells_for_geo_points(geodf_points_wgs84=geodf_points_wgs84, cell_ids_only=True, dggs_type='ISEA4H', resolution=8)\nprint(gdf5.head())\ngdf5.to_file('geopoint_cellids_from_points_isea4h_8.shp')\n\n# generate DGGS grid cell polygons based on 'cell_id_list' (a list or np.array of provided cell_ids)\ngdf6 = dggrid_instance.grid_cell_polygons_from_cellids(cell_id_list=[1, 4, 8], 'ISEA7H', 5)\nprint(gdf6.head())\ngdf6.to_file('from_seqnums_isea7h_5.shp')\n\n# v0.2.6 API update split at dateline for cartesian GIS tools\ngdf7 = dggrid_instance.grid_cell_polygons_for_extent('ISEA7H', 3, split_dateline=True)\ngdf7.to_file('global_isea7h_3_interrupted.shp')\n\ngdf_z1 = dggrid_instance.grid_cell_polygons_for_extent('IGEO7', 5, clip_geom=est_bound, output_address_type='Z7_STRING')\nprint(gdf_z1.head(3))\n\ndf_z1 = dggrid_instance.guess_zstr_resolution(gdf_z1['name'].values, 'IGEO7', input_address_type='Z7_STRING')\nprint(df_z1.head(3))\n\ndf_q2di = dggrid_instance.address_transform(gdf_z1['name'].values, 'IGEO7', 5, input_address_type='Z7_STRING', output_address_type='Q2DI')\nprint(df_q2di.head(3))\n\ndf_tri = dggrid_instance.address_transform(gdf_z1['name'].values, 'IGEO7', 5, input_address_type='Z7_STRING', output_address_type='PROJTRI')\nprint(df_tri.head(3))\n\n```\n\n## TODO:\n\n- get parent_for_cell_id at coarser resolution\n- get children_for_cell_id at finer resolution\n\n## Related work:\n\nOriginally insprired by [dggridR](https://github.com/r-barnes/dggridR), Richard Barnes\u2019 R interface to DGGRID. However, dggridR is directly linked via Rcpp to DGGRID and calls native C/C++ functions.\n\nAfter some unsuccessful trials with ctypes, cython, CFFI, pybind11 or cppyy (rather due to lack of experience) I found [am2222/pydggrid](https://github.com/am2222/pydggrid) ([on PyPI](https://pypi.org/project/pydggrid/)) which made apparently some initial scaffolding for the transform operation with [pybind11](https://pybind11.readthedocs.io/en/master/) 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.\n\n\n## Bundling for different operating systems\n\nHaving to compile DGGRID for Windows can be a bit challenging. We are\nworking on an updated conda package. Currently DGGRID v7.8 is available on conda-forge:\n\n[](https://anaconda.org/conda-forge/dggrid)\n\n## greater context DGGS in Earth Sciences and GIS\n\nSome reading to be excited about: [discourse.pangeo.io](https://discourse.pangeo.io/t/discrete-global-grid-systems-dggs-use-with-pangeo/2274)\n\n\n",
"bugtrack_url": null,
"license": "AGPL-3.0-or-later",
"summary": "a Python library to run highlevel functions of DGGRIDv7 and v8",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/allixender/dggrid4py",
"Repository": "https://github.com/allixender/dggrid4py"
},
"split_keywords": [
"python",
" gis",
" dggs",
" dggrid",
" hexagons",
" grids",
" spatial statistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d826a39a514b0ed4d274da9b15ccd7c2f23c3017554b3b5f33d44535e7423e76",
"md5": "707cf698f989975e96dda83435d7df44",
"sha256": "3a446f6247483d561b425ea13fd7180de32e30d76f14a2cb63c706a6c6805f05"
},
"downloads": -1,
"filename": "dggrid4py-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "707cf698f989975e96dda83435d7df44",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8",
"size": 28490,
"upload_time": "2024-11-19T14:40:49",
"upload_time_iso_8601": "2024-11-19T14:40:49.352523Z",
"url": "https://files.pythonhosted.org/packages/d8/26/a39a514b0ed4d274da9b15ccd7c2f23c3017554b3b5f33d44535e7423e76/dggrid4py-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e2acbf3559f11be497ce5bb69c9d225b2a30987a37b6b84e4982359124fb9db",
"md5": "31ab9f8762b51ecfe3b986fe2f7c011c",
"sha256": "ff4e8e682fd4aaf6e7f6f7df5a5ae13374996332c2e08adc690853d19ebe5920"
},
"downloads": -1,
"filename": "dggrid4py-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "31ab9f8762b51ecfe3b986fe2f7c011c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8",
"size": 29757,
"upload_time": "2024-11-19T14:40:50",
"upload_time_iso_8601": "2024-11-19T14:40:50.348732Z",
"url": "https://files.pythonhosted.org/packages/4e/2a/cbf3559f11be497ce5bb69c9d225b2a30987a37b6b84e4982359124fb9db/dggrid4py-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 14:40:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allixender",
"github_project": "dggrid4py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dggrid4py"
}
JSON
