Skip to content

H3Neighbourhood

Bases: Neighbourhood[str]

H3 Neighbourhood.

This class allows to get the neighbours of an H3 region.

Source code in srai/neighbourhoods/h3_neighbourhood.py 
14
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
class H3Neighbourhood(Neighbourhood[str]):
    """
    H3 Neighbourhood.

    This class allows to get the neighbours of an H3 region.
    """

    def __init__(self, regions_gdf: Optional[gpd.GeoDataFrame] = None) -> None:
        """
        Initializes the H3Neighbourhood.

        If a regions GeoDataFrame is provided, only the neighbours
        that are in the regions GeoDataFrame will be returned by the methods of this instance.
        NOTICE: If a region is a part of the k-th ring of a region
            and is included in the GeoDataFrame, it will be returned
            by get_neighbours_at_distance method with distance k
            even when there is no path of length k between the two regions.

        Args:
            regions_gdf (Optional[gpd.GeoDataFrame], optional): The regions that are being analyzed.
                The H3Neighbourhood will only look for neighbours among these regions.
                Defaults to None.
        """
        super().__init__()
        self._available_indices: Optional[Set[str]] = None
        if regions_gdf is not None:
            self._available_indices = set(regions_gdf.index)

    def get_neighbours(self, index: str) -> Set[str]:
        """
        Get the direct neighbours of an H3 region using its index.

        Args:
            index (str): H3 index of the region.

        Returns:
            Set[str]: Indexes of the neighbours.
        """
        return self.get_neighbours_up_to_distance(index, 1)

    def get_neighbours_up_to_distance(self, index: str, distance: int) -> Set[str]:
        """
        Get the neighbours of an H3 region up to a certain distance.

        Args:
            index (str): H3 index of the region.
            distance (int): Distance to the neighbours.

        Returns:
            Set[str]: Indexes of the neighbours up to the given distance.
        """
        if self._distance_incorrect(distance):
            return set()

        neighbours: Set[str] = h3.grid_disk(index, distance)
        neighbours.discard(index)
        return self._select_available(neighbours)

    def get_neighbours_at_distance(self, index: str, distance: int) -> Set[str]:
        """
        Get the neighbours of an H3 region at a certain distance.

        Args:
            index (str): H3 index of the region.
            distance (int): Distance to the neighbours.

        Returns:
            Set[str]: Indexes of the neighbours at the given distance.
        """
        if self._distance_incorrect(distance):
            return set()

        neighbours: Set[str] = h3.grid_ring(index, distance)
        neighbours.discard(index)
        return self._select_available(neighbours)

    def _select_available(self, indices: Set[str]) -> Set[str]:
        if self._available_indices is None:
            return indices
        return indices.intersection(self._available_indices)

    def _distance_incorrect(self, distance: int) -> bool:
        return distance <= 0

__init__ 

__init__(regions_gdf: Optional[gpd.GeoDataFrame] = None) -> None

Initializes the H3Neighbourhood.

If a regions GeoDataFrame is provided, only the neighbours that are in the regions GeoDataFrame will be returned by the methods of this instance.

If a region is a part of the k-th ring of a region

and is included in the GeoDataFrame, it will be returned by get_neighbours_at_distance method with distance k even when there is no path of length k between the two regions.

PARAMETER DESCRIPTION
regions_gdf

The regions that are being analyzed. The H3Neighbourhood will only look for neighbours among these regions. Defaults to None.

TYPE: Optional[gpd.GeoDataFrame] DEFAULT: None

Source code in srai/neighbourhoods/h3_neighbourhood.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def __init__(self, regions_gdf: Optional[gpd.GeoDataFrame] = None) -> None:
    """
    Initializes the H3Neighbourhood.

    If a regions GeoDataFrame is provided, only the neighbours
    that are in the regions GeoDataFrame will be returned by the methods of this instance.
    NOTICE: If a region is a part of the k-th ring of a region
        and is included in the GeoDataFrame, it will be returned
        by get_neighbours_at_distance method with distance k
        even when there is no path of length k between the two regions.

    Args:
        regions_gdf (Optional[gpd.GeoDataFrame], optional): The regions that are being analyzed.
            The H3Neighbourhood will only look for neighbours among these regions.
            Defaults to None.
    """
    super().__init__()
    self._available_indices: Optional[Set[str]] = None
    if regions_gdf is not None:
        self._available_indices = set(regions_gdf.index)

get_neighbours 

get_neighbours(index: str) -> Set[str]

Get the direct neighbours of an H3 region using its index.

PARAMETER DESCRIPTION
index

H3 index of the region.

TYPE: str

RETURNS DESCRIPTION
Set[str]

Set[str]: Indexes of the neighbours.
Source code in srai/neighbourhoods/h3_neighbourhood.py 
42
43
44
45
46
47
48
49
50
51
52
def get_neighbours(self, index: str) -> Set[str]:
    """
    Get the direct neighbours of an H3 region using its index.

    Args:
        index (str): H3 index of the region.

    Returns:
        Set[str]: Indexes of the neighbours.
    """
    return self.get_neighbours_up_to_distance(index, 1)

get_neighbours_at_distance 

get_neighbours_at_distance(index: str, distance: int) -> Set[str]

Get the neighbours of an H3 region at a certain distance.

PARAMETER DESCRIPTION
index

H3 index of the region.

TYPE: str

distance

Distance to the neighbours.

TYPE: int

RETURNS DESCRIPTION
Set[str]

Set[str]: Indexes of the neighbours at the given distance.
Source code in srai/neighbourhoods/h3_neighbourhood.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def get_neighbours_at_distance(self, index: str, distance: int) -> Set[str]:
    """
    Get the neighbours of an H3 region at a certain distance.

    Args:
        index (str): H3 index of the region.
        distance (int): Distance to the neighbours.

    Returns:
        Set[str]: Indexes of the neighbours at the given distance.
    """
    if self._distance_incorrect(distance):
        return set()

    neighbours: Set[str] = h3.grid_ring(index, distance)
    neighbours.discard(index)
    return self._select_available(neighbours)

get_neighbours_up_to_distance 

get_neighbours_up_to_distance(index: str, distance: int) -> Set[str]

Get the neighbours of an H3 region up to a certain distance.

PARAMETER DESCRIPTION
index

H3 index of the region.

TYPE: str

distance

Distance to the neighbours.

TYPE: int

RETURNS DESCRIPTION
Set[str]

Set[str]: Indexes of the neighbours up to the given distance.
Source code in srai/neighbourhoods/h3_neighbourhood.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def get_neighbours_up_to_distance(self, index: str, distance: int) -> Set[str]:
    """
    Get the neighbours of an H3 region up to a certain distance.

    Args:
        index (str): H3 index of the region.
        distance (int): Distance to the neighbours.

    Returns:
        Set[str]: Indexes of the neighbours up to the given distance.
    """
    if self._distance_incorrect(distance):
        return set()

    neighbours: Set[str] = h3.grid_disk(index, distance)
    neighbours.discard(index)
    return self._select_available(neighbours)