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
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) -> None:
        """
        Init AdjacencyNeighbourhood.

        Args:
            regions_gdf (gpd.GeoDataFrame): regions for which a neighbourhood will be calculated.

        Raises:
            ValueError: If regions_gdf doesn't have geometry column.
        """
        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) -> Set[Hashable]:
        """
        Get the direct neighbours of any region using its index.

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

        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)

        return self.lookup[index]

    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) -> None

Init AdjacencyNeighbourhood.

PARAMETER DESCRIPTION
regions_gdf

regions for which a neighbourhood will be calculated.

TYPE: gpd.GeoDataFrame

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
def __init__(self, regions_gdf: gpd.GeoDataFrame) -> None:
    """
    Init AdjacencyNeighbourhood.

    Args:
        regions_gdf (gpd.GeoDataFrame): regions for which a neighbourhood will be calculated.

    Raises:
        ValueError: If regions_gdf doesn't have geometry column.
    """
    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 
41
42
43
44
45
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) -> Set[Hashable]

Get the direct neighbours of any region using its index.

PARAMETER DESCRIPTION
index

Unique identifier of the region.

TYPE: Hashable

RETURNS DESCRIPTION
Set[Hashable]

Set[Hashable]: Indexes of the neighbours.
Source code in srai/neighbourhoods/adjacency_neighbourhood.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def get_neighbours(self, index: Hashable) -> Set[Hashable]:
    """
    Get the direct neighbours of any region using its index.

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

    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)

    return self.lookup[index]