Index

This module contains joiners, used to match spatial data with regions used in analysis.

All methods for spatial embedding (available in srai) are designed to operate on regions, not on individual spatial features. This means that we need to match spatial features with our given regions. This can be done in different ways, all of which are available under a common Joiner interface.

Joiner

Bases: ABC

Abstract class for joiners.

transform(regions, features)

abstractmethod

Join features to regions.

PARAMETER	DESCRIPTION
regions	regions with which features are joined TYPE: GeoDataFrame
features	features to be joined TYPE: GeoDataFrame

Returns: GeoDataFrame with an intersection of regions and features, which contains a MultiIndex and optionally a geometry with the intersection

Source code in srai/joiners/_base.py

@abc.abstractmethod
def transform(
    self,
    regions: gpd.GeoDataFrame,
    features: gpd.GeoDataFrame,
) -> gpd.GeoDataFrame:  # pragma: no cover
    """
    Join features to regions.

    Args:
        regions (gpd.GeoDataFrame): regions with which features are joined
        features (gpd.GeoDataFrame): features to be joined
    Returns:
        GeoDataFrame with an intersection of regions and features, which contains
        a MultiIndex and optionally a geometry with the intersection
    """
    raise NotImplementedError

IntersectionJoiner

Bases: Joiner

Intersection Joiner.

Intersection Joiner allows to join two GeoDataFrames and find all overlapping geometries. It does not apply any grouping or aggregation.

transform(regions, features, return_geom=False)

Join features to regions based on an 'intersects' predicate.

Does not apply any grouping to regions.

PARAMETER	DESCRIPTION
regions	regions with which features are joined TYPE: GeoDataFrame
features	features to be joined TYPE: GeoDataFrame
return_geom	whether to return geometry of the joined features. Defaults to False. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
GeoDataFrame	GeoDataFrame with an intersection of regions and features, which contains
GeoDataFrame	a MultiIndex and optionaly a geometry with the intersection

Source code in srai/joiners/intersection_joiner.py

def transform(
    self, regions: gpd.GeoDataFrame, features: gpd.GeoDataFrame, return_geom: bool = False
) -> gpd.GeoDataFrame:
    """
    Join features to regions based on an 'intersects' predicate.

    Does not apply any grouping to regions.

    Args:
        regions (gpd.GeoDataFrame): regions with which features are joined
        features (gpd.GeoDataFrame): features to be joined
        return_geom (bool): whether to return geometry of the joined features.
            Defaults to False.

    Returns:
        GeoDataFrame with an intersection of regions and features, which contains
        a MultiIndex and optionaly a geometry with the intersection
    """
    if GEOMETRY_COLUMN not in regions.columns:
        raise ValueError("Regions must have a geometry column.")
    if GEOMETRY_COLUMN not in features.columns:
        raise ValueError("Features must have a geometry column.")

    if len(regions) == 0:
        raise ValueError("Regions must not be empty.")
    if len(features) == 0:
        raise ValueError("Features must not be empty.")

    result_gdf: gpd.GeoDataFrame

    if return_geom:
        result_gdf = self._join_with_geom(regions, features)
    else:
        result_gdf = self._join_without_geom(regions, features)

    return result_gdf