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
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
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, include_center: bool = False
    ) -> 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.
            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.
        """
        super().__init__(include_center)
        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, include_center: Optional[bool] = None) -> Set[str]:
        """
        Get the direct neighbours of an H3 region using its index.

        Args:
            index (str): H3 index 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[str]: Indexes of the neighbours.
        """
        return self.get_neighbours_up_to_distance(index, 1, include_center)

    def get_neighbours_up_to_distance(
        self,
        index: str,
        distance: int,
        include_center: Optional[bool] = None,
        unchecked: bool = False,
    ) -> 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.
            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.
            unchecked (bool): Whether to check if the neighbours are in the available indices.

        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 = self._handle_center(
            index, distance, neighbours, at_distance=False, include_center_override=include_center
        )
        if unchecked:
            return neighbours
        return self._select_available(neighbours)

    def get_neighbours_at_distance(
        self, index: str, distance: int, include_center: Optional[bool] = None
    ) -> 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.
            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[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 = self._handle_center(
            index, distance, neighbours, at_distance=True, include_center_override=include_center
        )
        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, include_center: bool = False) -> 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

include_center

Whether to include the region itself in the neighbours.

TYPE: bool DEFAULT: False

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
41
42
43
44
45
def __init__(
    self, regions_gdf: Optional[gpd.GeoDataFrame] = None, include_center: bool = False
) -> 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.
        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.
    """
    super().__init__(include_center)
    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, include_center: Optional[bool] = None) -> Set[str]

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

PARAMETER DESCRIPTION
index

H3 index of the region.

TYPE: str

include_center

Whether to include the region itself in the neighbours.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Set[str]

Set[str]: Indexes of the neighbours.
Source code in srai/neighbourhoods/h3_neighbourhood.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
def get_neighbours(self, index: str, include_center: Optional[bool] = None) -> Set[str]:
    """
    Get the direct neighbours of an H3 region using its index.

    Args:
        index (str): H3 index 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[str]: Indexes of the neighbours.
    """
    return self.get_neighbours_up_to_distance(index, 1, include_center)

get_neighbours_at_distance 

get_neighbours_at_distance(index: str, distance: int, include_center: Optional[bool] = None) -> 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

include_center

Whether to include the region itself in the neighbours.

TYPE: Optional[bool] DEFAULT: None

RETURNS DESCRIPTION
Set[str]

Set[str]: Indexes of the neighbours at the given distance.
Source code in srai/neighbourhoods/h3_neighbourhood.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def get_neighbours_at_distance(
    self, index: str, distance: int, include_center: Optional[bool] = None
) -> 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.
        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[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 = self._handle_center(
        index, distance, neighbours, at_distance=True, include_center_override=include_center
    )
    return self._select_available(neighbours)

get_neighbours_up_to_distance 

get_neighbours_up_to_distance(index: str, distance: int, include_center: Optional[bool] = None, unchecked: bool = False) -> 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

include_center

Whether to include the region itself in the neighbours. If None, the value set in init is used. Defaults to None.

TYPE: Optional[bool] DEFAULT: None

unchecked

Whether to check if the neighbours are in the available indices.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
Set[str]

Set[str]: Indexes of the neighbours up to the given distance.
Source code in srai/neighbourhoods/h3_neighbourhood.py 
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
def get_neighbours_up_to_distance(
    self,
    index: str,
    distance: int,
    include_center: Optional[bool] = None,
    unchecked: bool = False,
) -> 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.
        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.
        unchecked (bool): Whether to check if the neighbours are in the available indices.

    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 = self._handle_center(
        index, distance, neighbours, at_distance=False, include_center_override=include_center
    )
    if unchecked:
        return neighbours
    return self._select_available(neighbours)