dggrid4py.DGGRIDv8

The DGGRIDv8 class is the class to use with DGGRID 8, for the classical DGGS types as well as for IGEO7. It selects the hierarchical indexes (Z3, Z7, ZORDER) through the address type HIERNDX and accepts the additional parameters of the DGGRID 8 series. The former address type names of the DGGRIDv7 class (e.g. Z7_STRING) are mapped to HIERNDX with a DeprecationWarning, see IGEO7.

The DGGRIDv7 class for DGGRID 7 is deprecated since version 0.6.0.

How to pass additional parameters to DGGRIDv8:

../_images/config_v8_extra.png
class dggrid4py.DGGRIDv8(executable='dggrid', working_dir=None, capture_logs=True, silent=False, tmp_geo_out_legacy=False, has_gdal=True, debug=False)

Parameter handling for DGGRID 8, for the classical DGGS types as well as for IGEO7 with the Z7 index.

__init__(executable='dggrid', working_dir=None, capture_logs=True, silent=False, tmp_geo_out_legacy=False, has_gdal=True, debug=False)

Methods

__init__([executable, working_dir, ...])

is_runnable()

check_gdal_support()

post_process_split_dateline(gdf)

run(dggs_meta_ops)

grid_cell_polygons_for_extent(dggs_type, ...)

generates a DGGS grid and returns all the cells as GeoDataFrame with geometry type Polygon

grid_cell_centroids_for_extent(dggs_type, ...)

generates a DGGS grid and returns all the cell's centroid as GeoDataFrame with geometry type Point

grid_cell_polygons_from_cellids(...[, ...])

generates a DGGS grid and returns all the cells as GeoDataFrame with geometry type Polygon

grid_cell_centroids_from_cellids(...[, ...])

generates a DGGS grid and returns all the cell's centroid as GeoDataFrame with geometry type Point

grid_cellids_for_extent(dggs_type, resolution)

generates a DGGS grid and returns all the cellids as a pandas dataframe

cells_for_geo_points(geodf_points_wgs84, ...)

takes a GeoDataFrame with point geometry and optional additional value columns and returns:

grid_stats_table(dggs_type, resolution[, ...])

generates the area and cell statistics for the given DGGS from resolution 0 to the given resolution of the DGGS

dgapi_grid_gen(dggs, subset_conf, output_conf)

Grid Generation.

dgapi_grid_stats(dggs)

Output Grid Statistics.

dgapi_grid_transform(dggs, subset_conf, ...)

Address Conversion.

dgapi_point_value_binning(dggs, subset_conf, ...)

Point Value Binning.

dgapi_pres_binning(dggs, subset_conf, ...)

Presence/Absence Binning.

cells_for_geo_points(geodf_points_wgs84, ...)

takes a GeoDataFrame with point geometry and optional additional value columns and returns:

address_transform(cell_id_list, dggs_type, ...)

generates the DGGS for the input cell_ids and returns all the transformed cell_ids cell_id_list is a list/numpy array, takes this list as seqnums ids (potentially also Z3, Z7, or ZORDER) the columns of the returned DataFrame are named after the given input and output address types
address_transform(cell_id_list: Sequence[str], dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, input_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING', 'INTERLEAVE', 'PLANE', 'HIERNDX'] = 'SEQNUM', output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING', 'HIERNDX'] = 'SEQNUM', **conf_extra: str | float | int) → DataFrame

generates the DGGS for the input cell_ids and returns all the transformed cell_ids cell_id_list is a list/numpy array, takes this list as seqnums ids (potentially also Z3, Z7, or ZORDER) the columns of the returned DataFrame are named after the given input and output address types

cells_for_geo_points(geodf_points_wgs84: GeoDataFrame, cell_ids_only: bool, dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, split_dateline: bool = False, output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING'] | Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'HIERNDX'] | None = None, **conf_extra: str | float | int) → GeoDataFrame
takes a GeoDataFrame with point geometry and optional additional value columns and returns:

  1. if cell_ids_only == True: a copy of the GeoDataFrame with the columns ‘lon’, ‘lat’ and the cell ids in ‘name’

  2. if cell_ids_only == False: a new GeoDataFrame with geometry type Polygon, the cell ids in ‘zone’, and the additional columns

The input GeoDataFrame is not modified. DGGRID takes the coordinates as lon/lat on its sphere, without a datum conversion. For IGEO7 the points have to be converted to authalic latitudes before (see dggrid4py.auxlat), or use dggrid4py.igeo7_ext.dggrid_igeo7_cells_for_geo_points, which does the conversion and returns the WGS84 points.

dgapi_grid_gen(dggs: Dggs, subset_conf: DggridMetaConfigT, output_conf: DggridMetaConfigT) → DggridApiOutputT

Grid Generation. Generate the cells of a DGG, either covering the complete surface of the earth or covering only a specific set of regions on the earth’s surface.

dgapi_grid_stats(dggs: Dggs) → DggridApiOutputT

Output Grid Statistics. Output a table of grid characteristics for the specified DGG.

dgapi_grid_transform(dggs: Dggs, subset_conf: DggridMetaConfigT, **conf_extra: str | float | int) → DggridApiOutputT

Address Conversion. Transform a file of locations from one address form (such as longitude/latitude) to another (such as DGG cell indexes).

dgapi_point_value_binning(dggs: Dggs, subset_conf: DggridMetaConfigT, **conf_extra: str | float | int) → DggridApiOutputT

Point Value Binning. Bin a set of floating-point values associated with point locations into the cells of a DGG, by assigning to each DGG cell the arithmetic mean of the values which are contained in that cell.

# specify the operation dggrid_operation BIN_POINT_VALS

# specify the DGG

dggs_type ISEA3H dggs_res_spec 9

# specify bin controls

bin_coverage PARTIAL input_files inputfiles/20k.txt inputfiles/50k.txt inputfiles/100k.txt inputfiles/200k.txt input_delimiter “ “

# specify the output

output_file_name outputfiles/popval3h9.txt output_address_type SEQNUM output_delimiter “,” output_count TRUE cell_output_control OUTPUT_OCCUPIED

dgapi_pres_binning(dggs: Dggs, subset_conf: DggridMetaConfigT, **conf_extra: str | float | int) → DggridApiOutputT

Presence/Absence Binning. Given a set of input files, each containing point locations associated with a particular class, DGGRID outputs, for each cell of a DGG, a vector indicating whether or not each class is present in that cell.

grid_cell_centroids_for_extent(dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, clip_geom: BaseGeometry | GeometryArray | None = None, output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING'] | Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'HIERNDX'] | None = None, **conf_extra: str | float | int) → GeoDataFrame
generates a DGGS grid and returns all the cell’s centroid as GeoDataFrame with geometry type Point

  1. if clip_geom is empty/None: grid cell ids/seqnums for the WHOLE_EARTH

  2. if clip_geom is a shapely shape geometry, takes this as a clip area

grid_cell_centroids_from_cellids(cell_id_list: Sequence[str], dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, clip_subset_type: Literal['SHAPEFILE', 'WHOLE_EARTH', 'GDAL', 'AIGEN', 'SEQNUMS', 'COARSE_CELLS', 'INPUT_ADDRESS_TYPE'] = 'WHOLE_EARTH', clip_cell_res: int = 1, input_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING', 'INTERLEAVE', 'PLANE', 'HIERNDX'] = 'SEQNUM', output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING', 'HIERNDX'] = 'SEQNUM', **conf_extra: str | float | int)
generates a DGGS grid and returns all the cell’s centroid as GeoDataFrame with geometry type Point

  1. if cell_id_list is empty/None: grid cells for the WHOLE_EARTH

  2. if cell_id_list is a list/numpy array, takes this list as seqnums ids (or as the given input_address_type) for subsetting

  3. with clip_subset_type=’COARSE_CELLS’, cell_id_list are coarser cells at clip_cell_res (a spatial clip, not the index children, see grid_cell_polygons_from_cellids)

grid_cell_polygons_for_extent(dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, clip_geom: BaseGeometry | GeometryArray | None = None, split_dateline: bool = False, output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING'] | Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'HIERNDX'] | None = None, **conf_extra: str | float | int) → GeoDataFrame
generates a DGGS grid and returns all the cells as GeoDataFrame with geometry type Polygon

  1. if clip_geom is empty/None: grid cell ids/seqnums for the WHOLE_EARTH

  2. if clip_geom is a shapely shape geometry, takes this as a clip area

grid_cell_polygons_from_cellids(cell_id_list: Sequence[str], dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, split_dateline: bool = False, clip_subset_type: Literal['SHAPEFILE', 'WHOLE_EARTH', 'GDAL', 'AIGEN', 'SEQNUMS', 'COARSE_CELLS', 'INPUT_ADDRESS_TYPE'] = 'WHOLE_EARTH', clip_cell_res: int = 1, input_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING', 'INTERLEAVE', 'PLANE', 'HIERNDX'] = 'SEQNUM', output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING', 'HIERNDX'] = 'SEQNUM', **conf_extra: str | float | int) → GeoDataFrame
generates a DGGS grid and returns all the cells as GeoDataFrame with geometry type Polygon

  1. if cell_id_list is empty/None: grid cells for the WHOLE_EARTH

  2. if cell_id_list is a list/numpy array, takes this list as seqnums ids (or as the given input_address_type) for subsetting

  3. with clip_subset_type=’COARSE_CELLS’, cell_id_list are coarser cells at clip_cell_res, and the cells at resolution that intersect them are returned. This is a spatial clip, not the index children: it includes cells of neighbouring parents that overlap, and over several resolutions it can miss index descendants.

grid_cellids_for_extent(dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None, clip_geom: BaseGeometry | GeometryArray | None = None, output_address_type: Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'Z3', 'Z3_STRING', 'Z7', 'Z7_STRING', 'ZORDER', 'ZORDER_STRING'] | Literal['GEO', 'Q2DI', 'SEQNUM', 'INTERLEAVE', 'PLANE', 'Q2DD', 'PROJTRI', 'VERTEX2DD', 'AIGEN', 'HIERNDX'] | None = None, **conf_extra: str | float | int) → DataFrame
generates a DGGS grid and returns all the cellids as a pandas dataframe

  1. if clip_geom is empty/None: grid cell ids/seqnums for the WHOLE_EARTH

  2. if clip_geom is a shapely shape geometry, takes this as a clip area

TODO could cellids be generated for COARSE_CELLS? Generate child id from list of parent ids?

grid_stats_table(dggs_type: Literal['CUSTOM', 'SUPERFUND', 'PLANETRISK', 'ISEA3H', 'ISEA4H', 'ISEA4T', 'ISEA4D', 'ISEA43H', 'ISEA7H', 'IGEO7', 'FULLER3H', 'FULLER4H', 'FULLER4T', 'FULLER4D', 'FULLER43H', 'FULLER7H'], resolution: int, mixed_aperture_level: int | None = None) → DataFrame

generates the area and cell statistics for the given DGGS from resolution 0 to the given resolution of the DGGS

read_geo_out(path: Path) → GeoDataFrame

reads a DGGRID geo output file, the cell id column is always ‘name’ and the CRS is EPSG:4326

DGGRID calls the cell id column differently depending on the output driver (‘global_id’ without GDAL). The coordinates are DGGRID’s lon/lat in degrees.

resolve_address_type(direction: Literal['input', 'output'], address_type: str | None, conf_extra: dict[str, str | float | int]) → str | None

checks an input or output address type against the address types of this DGGRID version

  • a DGGRIDv7 hierarchical index name (e.g. ‘Z7_STRING’) is mapped to its HIERNDX form on DGGRIDv8, with a DeprecationWarning, and the hier_ndx fields are added to conf_extra (if not set already)

  • any other address type that is not available raises a ValueError, instead of being ignored

  • if address_type is None, the value from conf_extra is used (and updated there), if there is one