Generators¶

A generator maps datasets onto points of interest or zones. The result is a view: those places with dataset attributes attached.

from gigaspatial import PoiViewGenerator, H3ViewGenerator, AdminBoundariesViewGenerator
from gigaspatial.generators import PoiViewGeneratorConfig, ZonalViewGeneratorConfig

Points¶

POI View Generator for multi-source attribute enrichment.

Integrates various geospatial datasets such as Google Open Buildings, Microsoft Global Buildings, GHSL (Built Surface/SMOD), and WorldPop with Points of Interest (POIs).

The POIs can be initialized from a list of (latitude, longitude) tuples, a list of dictionaries, a pandas DataFrame, or a geopandas GeoDataFrame.

`find_nearest_buildings(country, search_radius=1000, find_nearest_globally=False, **kwargs)` ¶

Finds the nearest building to each POI within a search radius.

Parameters:

Name	Type	Description	Default
`country`	`str`	ISO country code for building data.	required
`search_radius`	`float`	Maximum search distance in meters. Defaults to 1000.	`1000`
`find_nearest_globally`	`bool`	If True, searches across all neighboring countries. Defaults to False.	`False`
`**kwargs`		Extra parameters for building handlers.	`{}`

Returns:

Type	Description
`DataFrame`	A DataFrame with nearest building IDs and distances for each POI.

`map_wp_pop(country, map_radius_meters, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

Maps WorldPop population data to POIs.

Enriches POIs with statistical population counts within a specified buffer radius.

Parameters:

Name	Type	Description	Default
`country`	`Union[str, List[str]]`	ISO country code or list of codes to process.	required
`map_radius_meters`	`float`	Buffer distance in meters around each POI.	required
`resolution`		Dataset resolution in meters. Defaults to 1000.	`1000`
`predicate`	`Literal['centroid_within', 'intersects', 'fractional', 'within']`	Spatial relationship for aggregation. Defaults to "intersects".	`'intersects'`
`output_column`	`str`	Destination column name. Defaults to "population".	`'population'`
`**kwargs`		Extra arguments for WPPopulationHandler.	`{}`

Returns:

Type	Description
	The updated POI view DataFrame.

Raises:

Type	Description
`ValueError`	If 'age_structures' project is used with multiple countries simultaneously.

`map_smod(stat='median', dataset_year=2020, dataset_resolution=1000, output_column='smod_class', **kwargs)` ¶

Maps GHSL Settlement Model (SMOD) data to the POIs.

Samples the SMOD class value at each POI's location.

Parameters:

Name	Description	Default
`stat`	Aggregation statistic. Defaults to "median".	`'median'`
`dataset_year`	Year of GHSL data. Defaults to 2020.	`2020`
`dataset_resolution`	Resolution in meters. Defaults to 1000.	`1000`
`output_column`	Output column name. Defaults to "smod_class".	`'smod_class'`
`**kwargs`	Extra arguments for GHSLDataHandler.	`{}`

Returns:

Type	Description
`DataFrame`	The updated POI view DataFrame.

`map_built_s(map_radius_meters=150, stat='sum', dataset_year=2020, dataset_resolution=100, output_column='built_surface_m2', **kwargs)` ¶

Maps GHSL Built Surface (GHS_BUILT_S) data to POIs.

Enriches POIs with the estimated built surface area within a buffer.

Parameters:

Name	Type	Description	Default
`map_radius_meters`	`float`	Buffer distance in meters. Defaults to 150.	`150`
`stat`	`str`	Agregation statistic. Defaults to "sum".	`'sum'`
`dataset_year`		Year of GHSL data to use. Defaults to 2020.	`2020`
`dataset_resolution`		Resolution in meters. Defaults to 100.	`100`
`output_column`		Output column name. Defaults to "built_surface_m2".	`'built_surface_m2'`
`**kwargs`		Extra arguments for GHSLDataHandler.	`{}`

Returns:

Type	Description
`DataFrame`	The updated POI view DataFrame.

`map_google_buildings(handler=None, **kwargs)` ¶

Maps Google Open Buildings data to POIs by finding the nearest building.

Enriches the view with IDs and distances to the nearest Google building plus code for each POI.

Parameters:

Name	Type	Description	Default
`handler`	`Optional[GoogleOpenBuildingsHandler]`	Optional handler for Google Open Buildings data. If None, a default one is initialized.	`None`
`**kwargs`		Additional parameters passed to `handler.load_points`.	`{}`

Returns:

Type	Description
`DataFrame`	The updated POI view DataFrame.

`map_ms_buildings(handler=None, **kwargs)` ¶

Maps Microsoft Global Buildings data to POIs by finding the nearest building.

Enriches the view with IDs and distances to the nearest MS building for each POI.

Parameters:

Name	Type	Description	Default
`handler`	`Optional[MSBuildingsHandler]`	Optional handler for MS Buildings data. If None, a default one is initialized.	`None`
`**kwargs`		Additional parameters for the data reader.	`{}`

Returns:

Type	Description
`DataFrame`	The updated POI view DataFrame.

`map_nearest_points(points_df, id_column=None, lat_column=None, lon_column=None, output_prefix='nearest', **kwargs)` ¶

Enriches POIs with IDs and distances to their nearest neighbors.

Parameters:

Name	Type	Description	Default
`points_df`	`Union[DataFrame, GeoDataFrame]`	DataFrame containing the target points to search.	required
`id_column`	`Optional[str]`	Name of the column containing target point IDs. If None, uses the DataFrame index.	`None`
`lat_column`	`Optional[str]`	Name of the latitude column in `points_df`. If None, it is automatically detected.	`None`
`lon_column`	`Optional[str]`	Name of the longitude column in `points_df`. If None, it is automatically detected.	`None`
`output_prefix`	`str`	Prefix for the new '{prefix}_id' and '{prefix}_distance' columns. Defaults to "nearest".	`'nearest'`
`**kwargs`		Additional parameters for the distance calculator.	`{}`

Returns:

Type	Description
`DataFrame`	A DataFrame containing 'poi_id' and the generated mapping columns.

Raises:

Type	Description
`ValueError`	If coordinate columns cannot be detected or expected columns are missing from `points_df`.

`map_zonal_stats(data, stat='mean', map_radius_meters=None, output_column='zonal_stat', value_column=None, predicate='intersects', **kwargs)` ¶

Enriches POIs with zonal statistics from raster or polygon data.

Operates in three modes: 1. Raster point sampling: Samples values at exact POI locations. 2. Raster zonal stats: Calculates stats within circular POI buffers. 3. Polygon aggregation: Aggregates polygon data within POI buffers.

Parameters:

Name	Type	Description	Default
`data`	`Union[List[TifProcessor], GeoDataFrame]`	Data source (TifProcessor(s) or GeoDataFrame).	required
`stat`	`str`	Statistic to calculate (e.g., 'sum', 'mean'). Defaults to 'mean'.	`'mean'`
`map_radius_meters`	`Optional[float]`	Radius for circular POI buffers. If None, samples directly at point locations (raster only).	`None`
`output_column`	`str`	Destination column name. Defaults to "zonal_stat".	`'zonal_stat'`
`value_column`	`Optional[str]`	Target column for polygon aggregation.	`None`
`predicate`	`Literal['intersects', 'within', 'fractional']`	Spatial relationship for aggregation. Defaults to "intersects".	`'intersects'`
`**kwargs`		Extra parameters for sampling or aggregation.	`{}`

Returns:

Type	Description
`DataFrame`	The calculated results as a DataFrame with 'poi_id'.

Raises:

Type	Description
`ValueError`	If inputs are invalid or incomplete for the chosen mode.

`map_aqueduct_flood_hazard(handler=None, return_period='rp00100', flood_type='inunriver', climate_scenario='historical', year='1980', model='000000000WATCH', subsidence=None, projection=None, buffer_meters=500, output_column=None, **kwargs)` ¶

Maps WRI Aqueduct 3.0 flood hazard depth to POIs.

Loads the corresponding global Aqueduct raster and samples the mean flood inundation depth within a circular buffer around each POI using :meth:map_zonal_stats.

Parameters:

Name	Type	Description	Default
`handler`		Optional pre-built :class:`~gigaspatial.handlers.wri.AqueductFloodHandler`. If provided, it overrides other hazard parameters.	`None`
`return_period`	`str`	Return-period key, e.g. `"rp00100"`. Defaults to `"rp00100"`.	`'rp00100'`
`flood_type`	`str`	Flood type — `"inunriver"` (riverine) or `"inuncoast"` (coastal). Defaults to `"inunriver"`.	`'inunriver'`
`climate_scenario`	`str`	Climate scenario — `"historical"`, `"rcp4p5"`, or `"rcp8p5"`. Defaults to `"historical"`.	`'historical'`
`year`	`str`	Reference year. Defaults to `"1980"`.	`'1980'`
`model`	`Optional[str]`	Riverine only. GCM model token (e.g. `"000000000WATCH"`).	`'000000000WATCH'`
`subsidence`	`Optional[str]`	Coastal only. Subsidence assumption — `"nosub"` or `"wtsub"`.	`None`
`projection`	`Optional[str]`	Coastal only. Projection percentile — `"0"`, `"0_perc_05"`, or `"0_perc_50"`.	`None`
`buffer_meters`	`float`	Sampling buffer radius in metres. Mean flood depth within this circle is used as the POI value. Defaults to 500.	`500`
`output_column`	`Optional[str]`	Optional column name. If `None`, the filename (without extension) plus `_meters` is used.	`None`
`**kwargs`		Forwarded to the handler's `load_data` call.	`{}`

Returns:

Type	Description
`DataFrame`	The updated POI view DataFrame.

Zones¶

Bases: GeometryBasedZonalViewGenerator[T]

Generates zonal views using H3 hexagons as the zones.

Mirrors MercatorViewGenerator/S2ViewGenerator but uses H3 cells (resolutions 0-15). The input source defines the area/cells and resolution determines the granularity.

Supported sources: - Country string → CountryH3Hexagons.create - Shapely geometry or GeoDataFrame → H3Hexagons.from_spatial - List of points (shapely Points or (lon, lat) tuples) → from_spatial - List of H3 indexes (strings) → H3Hexagons.from_hexagons

`map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

`map_ghsl_pop(resolution=100, stat='sum', output_column='ghsl_pop', predicate='intersects', **kwargs)` ¶

`map_smod(year=2020, resolution=1000, stat='median', output_column='smod_class', **kwargs)` ¶

Map GHSL Settlement Model data to zones.

Convenience method for mapping Global Human Settlement Layer Settlement Model data using appropriate default parameters for settlement classification analysis.

Parameters:

Name	Type	Description	Default
`year`		The year of the data (default: 2020)	`2020`
`resolution`		The resolution in meters (default: 1000)	`1000`
`stat`	`str`	Statistic to calculate for settlement class values within each zone. Defaults to "median" which gives the predominant settlement class.	`'median'`
`output_column`	`str`	The output column name. Defaults to "smod_class".	`'smod_class'`

`map_built_s(year=2020, resolution=100, stat='sum', output_column='built_surface_m2', **kwargs)` ¶

Map GHSL Built-up Surface data to zones.

Convenience method for mapping Global Human Settlement Layer Built-up Surface data using appropriate default parameters for built surface analysis.

Parameters:

Name	Type	Description	Default
`year`		The year of the data (default: 2020)	`2020`
`resolution`		The resolution in meters (default: 100)	`100`
`stat`	`str`	Statistic to calculate for built surface values within each zone. Defaults to "sum" which gives total built surface area.	`'sum'`
`output_column`	`str`	The output column name. Defaults to "built_surface_m2".	`'built_surface_m2'`

`map_buildings(country=None, output_column='building_count', **kwargs)` ¶

`map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs)` ¶

`map_ghsl(handler, stat, output_column=None, **kwargs)` ¶

Map Global Human Settlement Layer data to zones.

Loads and processes GHSL raster data for the intersecting tiles, then samples the raster values within each zone using the specified statistic.

Parameters:

Name	Type	Description	Default
`hander`	`GHSLDataHandler`	Handler for the GHSL data.	required
`stat`	`str`	Statistic to calculate for raster values within each zone. Common options: "mean", "sum", "median", "min", "max".	required
`output_column`	`str`	The output column name. If None, uses the GHSL product name in lowercase followed by underscore.	`None`

Returns:

Type	Description
`DataFrame`	pd.DataFrame: Updated DataFrame with GHSL metrics. Adds a column named as `output_column` containing the sampled values.

Note

The method automatically determines which GHSL tiles intersect with the zones and loads only the necessary data for efficient processing.

`map_google_buildings(handler=None, use_polygons=False, **kwargs)` ¶

Map Google Open Buildings data to zones.

Processes Google Open Buildings dataset to calculate building counts and total building area within each zone. Can use either point centroids (faster) or polygon geometries (more accurate) for spatial operations.

Parameters:

Name	Type	Description	Default
`google_open_buildings_config`	`GoogleOpenBuildingsConfig`	Configuration for accessing Google Open Buildings data. Uses default configuration if not provided.	required
`use_polygons`	`bool`	Whether to use polygon geometries for buildings. If True, uses actual building polygons for more accurate area calculations but with slower performance. If False, uses building centroids with area values from attributes for faster processing. Defaults to False.	`False`

Returns:

Type	Description
`DataFrame`	pd.DataFrame: Updated DataFrame with building metrics. Adds columns: - 'google_buildings_count': Number of buildings in each zone - 'google_buildings_area_in_meters': Total building area in square meters

Note

If no Google Buildings data is found for the zones, returns the original GeoDataFrame unchanged with a warning logged.

`map_ms_buildings(handler=None, use_polygons=False)` ¶

Map Microsoft Global Buildings data to zones.

Processes Microsoft Global Buildings dataset to calculate building counts and total building area within each zone. Can use either centroid points (faster) or polygon geometries (more accurate) for spatial operations.

Parameters:

Name	Type	Description	Default
`ms_buildings_config`	`MSBuildingsConfig`	Configuration for accessing Microsoft Global Buildings data. If None, uses default configuration.	required
`use_polygons`	`bool`	Whether to use polygon geometries for buildings. If True, uses actual building polygons for more accurate area calculations but with slower performance. If False, uses building centroids with area values from attributes for faster processing. Defaults to False.	`False`

Returns:

Type	Description
`GeoDataFrame`	gpd.GeoDataFrame: Updated GeoDataFrame with zones and building metrics. Adds columns: - 'ms_buildings_count': Number of buildings in each zone - 'ms_buildings_area_in_meters': Total building area in square meters

Note

If no Microsoft Buildings data is found for the zones, returns the original GeoDataFrame unchanged with a warning logged. Building areas are calculated in meters using appropriate UTM projections.

Bases: GeometryBasedZonalViewGenerator[T]

Generates zonal views using Google S2 cells as the zones.

This mirrors the MercatorViewGenerator but uses S2 cells (levels 0-30) as zone units. The primary input source defines the geographic area of interest and the level determines the granularity of S2 cells.

Attributes:

Name	Type	Description
`source`	`Union[str, BaseGeometry, GeoDataFrame, List[Union[Point, Tuple[float, float]]], List[Union[int, str]]]`	Specifies the geographic area or specific cells to use. Can be: - A country name (str): Uses `CountryS2Cells` to generate cells covering the country. - A Shapely geometry (BaseGeometry): Uses `S2Cells.from_spatial` to create cells intersecting the geometry. - A GeoDataFrame (gpd.GeoDataFrame): Uses `S2Cells.from_spatial` to create cells intersecting geometries or from points. - A list of points (List[Union[Point, Tuple[float, float]]]): Uses `S2Cells.from_points` via `from_spatial`. - A list of cell identifiers (List[Union[int, str]]): Uses `S2Cells.from_cells` (accepts integer IDs or token strings).
`level`	`int`	The S2 level (0-30). Higher levels produce smaller cells.
`config`	`Optional[ZonalViewGeneratorConfig]`	Configuration for generation.
`data_store`	`Optional[DataStore]`	Optional data store instance.
`logger`	`Optional[Logger]`	Optional logger.

`map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

`map_buildings(country=None, output_column='building_count', **kwargs)` ¶

`map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs)` ¶

Bases: GeometryBasedZonalViewGenerator[T]

Generates zonal views using Mercator tiles as the zones.

This class specializes in creating zonal views where the zones are defined by Mercator tiles. It extends the GeometryBasedZonalViewGenerator and leverages the MercatorTiles and CountryMercatorTiles classes to generate tiles based on various input sources.

The primary input source defines the geographical area of interest. This can be a country, a specific geometry, a set of points, or even a list of predefined quadkeys. The zoom_level determines the granularity of the Mercator tiles.

Attributes:

Name	Type	Description
`source`	`Union[str, BaseGeometry, GeoDataFrame, List[Union[Point, Tuple[float, float]]], List[str]]`	Specifies the geographic area or specific tiles to use. Can be: - A country name (str): Uses `CountryMercatorTiles` to generate tiles covering the country. - A Shapely geometry (BaseGeometry): Uses `MercatorTiles.from_spatial` to create tiles intersecting the geometry. - A GeoDataFrame (gpd.GeoDataFrame): Uses `MercatorTiles.from_spatial` to create tiles intersecting the geometries. - A list of points (List[Union[Point, Tuple[float, float]]]): Uses `MercatorTiles.from_spatial` to create tiles containing the points. - A list of quadkeys (List[str]): Uses `MercatorTiles.from_quadkeys` to use the specified tiles directly.
`zoom_level`	`int`	The zoom level of the Mercator tiles. Higher zoom levels result in smaller, more detailed tiles.
`predicate`	`str`	The spatial predicate used when filtering tiles based on a spatial source (e.g., "intersects", "contains"). Defaults to "intersects".
`config`	`Optional[ZonalViewGeneratorConfig]`	Configuration for the zonal view generation process.
`data_store`	`Optional[DataStore]`	A DataStore instance for accessing data.
`logger`	`Optional[Logger]`	A logger instance for logging.

Methods:

Name	Description
`_init_zone_data`	Initializes the Mercator tile GeoDataFrame based on the input source.
`# Inherits other methods from GeometryBasedZonalViewGenerator, such as`

Example

Create a MercatorViewGenerator for tiles covering Germany at zoom level 6¶

generator = MercatorViewGenerator(source="Germany", zoom_level=6)

Create a MercatorViewGenerator for tiles intersecting a specific polygon¶

polygon = ... # Define a Shapely Polygon generator = MercatorViewGenerator(source=polygon, zoom_level=8)

Create a MercatorViewGenerator from a list of quadkeys¶

quadkeys = ["0020023131023032", "0020023131023033"] generator = MercatorViewGenerator(source=quadkeys, zoom_level=12)

Generators¶

Points¶

find_nearest_buildings(country, search_radius=1000, find_nearest_globally=False, **kwargs) ¶

map_wp_pop(country, map_radius_meters, resolution=1000, predicate='intersects', output_column='population', **kwargs) ¶

map_smod(stat='median', dataset_year=2020, dataset_resolution=1000, output_column='smod_class', **kwargs) ¶

map_built_s(map_radius_meters=150, stat='sum', dataset_year=2020, dataset_resolution=100, output_column='built_surface_m2', **kwargs) ¶

map_google_buildings(handler=None, **kwargs) ¶

map_ms_buildings(handler=None, **kwargs) ¶

map_nearest_points(points_df, id_column=None, lat_column=None, lon_column=None, output_prefix='nearest', **kwargs) ¶

map_zonal_stats(data, stat='mean', map_radius_meters=None, output_column='zonal_stat', value_column=None, predicate='intersects', **kwargs) ¶

map_aqueduct_flood_hazard(handler=None, return_period='rp00100', flood_type='inunriver', climate_scenario='historical', year='1980', model='000000000WATCH', subsidence=None, projection=None, buffer_meters=500, output_column=None, **kwargs) ¶

Zones¶

map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs) ¶

map_ghsl_pop(resolution=100, stat='sum', output_column='ghsl_pop', predicate='intersects', **kwargs) ¶

map_smod(year=2020, resolution=1000, stat='median', output_column='smod_class', **kwargs) ¶

map_built_s(year=2020, resolution=100, stat='sum', output_column='built_surface_m2', **kwargs) ¶

map_buildings(country=None, output_column='building_count', **kwargs) ¶

map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs) ¶

map_ghsl(handler, stat, output_column=None, **kwargs) ¶

map_google_buildings(handler=None, use_polygons=False, **kwargs) ¶

map_ms_buildings(handler=None, use_polygons=False) ¶

map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs) ¶

map_buildings(country=None, output_column='building_count', **kwargs) ¶

map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs) ¶

Create a MercatorViewGenerator for tiles covering Germany at zoom level 6¶

Create a MercatorViewGenerator for tiles intersecting a specific polygon¶

Create a MercatorViewGenerator from a list of quadkeys¶

map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs) ¶

map_buildings(country=None, output_column='building_count', **kwargs) ¶

map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs) ¶

`find_nearest_buildings(country, search_radius=1000, find_nearest_globally=False, **kwargs)` ¶

`map_wp_pop(country, map_radius_meters, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

`map_smod(stat='median', dataset_year=2020, dataset_resolution=1000, output_column='smod_class', **kwargs)` ¶

`map_built_s(map_radius_meters=150, stat='sum', dataset_year=2020, dataset_resolution=100, output_column='built_surface_m2', **kwargs)` ¶

`map_google_buildings(handler=None, **kwargs)` ¶

`map_ms_buildings(handler=None, **kwargs)` ¶

`map_nearest_points(points_df, id_column=None, lat_column=None, lon_column=None, output_prefix='nearest', **kwargs)` ¶

`map_zonal_stats(data, stat='mean', map_radius_meters=None, output_column='zonal_stat', value_column=None, predicate='intersects', **kwargs)` ¶

`map_aqueduct_flood_hazard(handler=None, return_period='rp00100', flood_type='inunriver', climate_scenario='historical', year='1980', model='000000000WATCH', subsidence=None, projection=None, buffer_meters=500, output_column=None, **kwargs)` ¶

`map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

`map_ghsl_pop(resolution=100, stat='sum', output_column='ghsl_pop', predicate='intersects', **kwargs)` ¶

`map_smod(year=2020, resolution=1000, stat='median', output_column='smod_class', **kwargs)` ¶

`map_built_s(year=2020, resolution=100, stat='sum', output_column='built_surface_m2', **kwargs)` ¶

`map_buildings(country=None, output_column='building_count', **kwargs)` ¶

`map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs)` ¶

`map_ghsl(handler, stat, output_column=None, **kwargs)` ¶

`map_google_buildings(handler=None, use_polygons=False, **kwargs)` ¶

`map_ms_buildings(handler=None, use_polygons=False)` ¶

`map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

`map_buildings(country=None, output_column='building_count', **kwargs)` ¶

`map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs)` ¶

`map_wp_pop(country=None, resolution=1000, predicate='intersects', output_column='population', **kwargs)` ¶

`map_buildings(country=None, output_column='building_count', **kwargs)` ¶

`map_rwi(country=None, predicate='intersects', aggregation='mean', output_column='rwi', **kwargs)` ¶