Skip to content

AdjacencyNeighbourhood

Bases: Neighbourhood[Hashable]

Adjacency Neighbourhood.

This class allows to get the neighbours of any region based on common border. Additionally, a lookup table is implemented to accelerate repeated queries.

By default, a lookup table will be populated lazily based on queries. A dedicated function generate_neighbourhoods allows for precalculation of all the neighbourhoods at once.

Source code in srai/neighbourhoods/adjacency_neighbourhood.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
class AdjacencyNeighbourhood(Neighbourhood[Hashable]):
    """
    Adjacency Neighbourhood.

    This class allows to get the neighbours of any region based on common border. Additionally, a
    lookup table is implemented to accelerate repeated queries.

    By default, a lookup table will be populated lazily based on queries. A dedicated function
    `generate_neighbourhoods` allows for precalculation of all the neighbourhoods at once.
    """

    def __init__(self, regions_gdf: gpd.GeoDataFrame, include_center: bool = False) -> None:
        """
        Init AdjacencyNeighbourhood.

        Args:
            regions_gdf (gpd.GeoDataFrame): regions for which a neighbourhood will be calculated.
            include_center (bool): Whether to include the region itself in the neighbours.
            This is the default value used for all the methods of the class,
            unless overridden in the function call.

        Raises:
            ValueError: If regions_gdf doesn't have geometry column.
        """
        super().__init__(include_center)
        if GEOMETRY_COLUMN not in regions_gdf.columns:
            raise ValueError("Regions must have a geometry column.")
        self.regions_gdf = regions_gdf
        self.lookup: Dict[Hashable, Set[Hashable]] = {}

    def generate_neighbourhoods(self) -> None:
        """Generate the lookup table for all regions."""
        for region_id in self.regions_gdf.index:
            if region_id not in self.lookup:
                self.lookup[region_id] = self._get_adjacent_neighbours(region_id)

    def get_neighbours(
        self, index: Hashable, include_center: Optional[bool] = None
    ) -> Set[Hashable]:
        """
        Get the direct neighbours of any region using its index.

        Args:
            index (Hashable): Unique identifier of the region.
            include_center (Optional[bool]): Whether to include the region itself in the neighbours.
            If None, the value set in __init__ is used. Defaults to None.

        Returns:
            Set[Hashable]: Indexes of the neighbours.
        """
        if self._index_incorrect(index):
            return set()

        if index not in self.lookup:
            self.lookup[index] = self._get_adjacent_neighbours(index)

        neighbours = self.lookup[index]
        neighbours = self._handle_center(
            index, 1, neighbours, at_distance=False, include_center_override=include_center
        )
        return neighbours

    def _get_adjacent_neighbours(self, index: Hashable) -> Set[Hashable]:
        """
        Get the direct neighbours of a region using `touches` [1] operator from the Shapely library.

        Args:
            index (Hashable): Unique identifier of the region.

        Returns:
            Set[Hashable]: Indexes of the neighbours.

        References:
            1. https://shapely.readthedocs.io/en/stable/reference/shapely.touches.html
        """
        current_region = self.regions_gdf.loc[index]
        neighbours = self.regions_gdf[
            self.regions_gdf.geometry.touches(current_region[GEOMETRY_COLUMN])
        ]
        return set(neighbours.index)

    def _index_incorrect(self, index: Hashable) -> bool:
        return index not in self.regions_gdf.index

__init__ 

__init__(regions_gdf: gpd.GeoDataFrame, include_center: bool = False) -> None

Init AdjacencyNeighbourhood.

PARAMETER DESCRIPTION
regions_gdf

regions for which a neighbourhood will be calculated.

TYPE: gpd.GeoDataFrame

include_center

Whether to include the region itself in the neighbours.

TYPE: bool DEFAULT: False

RAISES DESCRIPTION
ValueError

If regions_gdf doesn't have geometry column.
Source code in srai/neighbourhoods/adjacency_neighbourhood.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def __init__(self, regions_gdf: gpd.GeoDataFrame, include_center: bool = False) -> None:
    """
    Init AdjacencyNeighbourhood.

    Args:
        regions_gdf (gpd.GeoDataFrame): regions for which a neighbourhood will be calculated.
        include_center (bool): Whether to include the region itself in the neighbours.
        This is the default value used for all the methods of the class,
        unless overridden in the function call.

    Raises:
        ValueError: If regions_gdf doesn't have geometry column.
    """
    super().__init__(include_center)
    if GEOMETRY_COLUMN not in regions_gdf.columns:
        raise ValueError("Regions must have a geometry column.")
    self.regions_gdf = regions_gdf
    self.lookup: Dict[Hashable, Set[Hashable]] = {}

generate_neighbourhoods 

generate_neighbourhoods() -> None

Generate the lookup table for all regions.

Source code in srai/neighbourhoods/adjacency_neighbourhood.py 
45
46
47
48
49
def generate_neighbourhoods(self) -> None:
    """Generate the lookup table for all regions."""
    for region_id in self.regions_gdf.index:
        if region_id not in self.lookup:
            self.lookup[region_id] = self._get_adjacent_neighbours(region_id)

get_neighbours 

get_neighbours(index: Hashable, include_center: Optional[bool] = None) -> Set[Hashable]

Get the direct neighbours of any region using its index.

PARAMETER DESCRIPTION
index

Unique identifier of the region.

TYPE: Hashable

include_center

Whether to include the region itself in the neighbours.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Set[Hashable]

Set[Hashable]: Indexes of the neighbours.
Source code in srai/neighbourhoods/adjacency_neighbourhood.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def get_neighbours(
    self, index: Hashable, include_center: Optional[bool] = None
) -> Set[Hashable]:
    """
    Get the direct neighbours of any region using its index.

    Args:
        index (Hashable): Unique identifier of the region.
        include_center (Optional[bool]): Whether to include the region itself in the neighbours.
        If None, the value set in __init__ is used. Defaults to None.

    Returns:
        Set[Hashable]: Indexes of the neighbours.
    """
    if self._index_incorrect(index):
        return set()

    if index not in self.lookup:
        self.lookup[index] = self._get_adjacent_neighbours(index)

    neighbours = self.lookup[index]
    neighbours = self._handle_center(
        index, 1, neighbours, at_distance=False, include_center_override=include_center
    )
    return neighbours