Neighbourhood

srai.neighbourhoods.Neighbourhood(include_center=False)

Bases: ABC, Generic[IndexType]

Neighbourhood interface.

This class abstracts away getting the neighbours of a region. It allows to get the neighbours at a certain distance or up to a certain distance. It is worth noting, that the distance here is not a metric distance, but a number of hops. This definition makes most sense semantically for grid systems such as H3 or S2 but should work for arbitrary neighbourhoods as well.

The subclasses only need to implement the get_neighbours method, but can also override the get_neighbours_up_to_distance and get_neighbours_at_distance methods for performance reasons. See the H3Neighbourhood class for an example. The class also provides a _handle_center method, which can be used to handle including/excluding the center region.

PARAMETER	DESCRIPTION
include_center	Whether to include the region itself in the neighbours. TYPE: bool DEFAULT: False

Source code in srai/neighbourhoods/_base.py

def __init__(self, include_center: bool = False) -> None:
    """
    Initializes the Neighbourhood.

    Args:
        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__()
    self.include_center = include_center

get_neighbours(index, include_center=None)

abstractmethod

Get the direct neighbours of a region using its index.

PARAMETER	DESCRIPTION
index	Unique identifier of the region. Dependant on the implementation. TYPE: IndexType
include_center	Whether to include the region itself in the neighbours. TYPE: Optional[bool] DEFAULT: None

RETURNS	DESCRIPTION
set[IndexType]	Set[IndexType]: Indexes of the neighbours.

Source code in srai/neighbourhoods/_base.py

@abstractmethod
def get_neighbours(
    self, index: IndexType, include_center: Optional[bool] = None
) -> set[IndexType]:
    """
    Get the direct neighbours of a region using its index.

    Args:
        index (IndexType): Unique identifier of the region.
            Dependant on the implementation.
        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[IndexType]: Indexes of the neighbours.
    """

get_neighbours_up_to_distance(
    index, distance, include_center=None
)

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

PARAMETER	DESCRIPTION
index	Unique identifier of the region. Dependant on the implementation. TYPE: IndexType
distance	Maximum 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[IndexType]	Set[IndexType]: Indexes of the neighbours.

Source code in srai/neighbourhoods/_base.py

def get_neighbours_up_to_distance(
    self, index: IndexType, distance: int, include_center: Optional[bool] = None
) -> set[IndexType]:
    """
    Get the neighbours of a region up to a certain distance.

    Args:
        index (IndexType): Unique identifier of the region.
            Dependant on the implementation.
        distance (int): Maximum 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[IndexType]: Indexes of the neighbours.
    """
    neighbours_with_distances = self._get_neighbours_with_distances(index, distance)
    neighbours: set[IndexType] = (
        seq(neighbours_with_distances).map(operator.itemgetter(0)).to_set()
    )
    neighbours = self._handle_center(
        index,
        distance,
        neighbours,
        at_distance=False,
        include_center_override=include_center,
    )
    return neighbours

get_neighbours_at_distance(
    index, distance, include_center=None
)

Get the neighbours of a region at a certain distance.

PARAMETER	DESCRIPTION
index	Unique identifier of the region. Dependant on the implementation. TYPE: IndexType
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[IndexType]	Set[IndexType]: Indexes of the neighbours.

Source code in srai/neighbourhoods/_base.py

def get_neighbours_at_distance(
    self, index: IndexType, distance: int, include_center: Optional[bool] = None
) -> set[IndexType]:
    """
    Get the neighbours of a region at a certain distance.

    Args:
        index (IndexType): Unique identifier of the region.
            Dependant on the implementation.
        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[IndexType]: Indexes of the neighbours.
    """
    neighbours_up_to_distance = self._get_neighbours_with_distances(index, distance)
    neighbours_at_distance: set[IndexType] = (
        seq(neighbours_up_to_distance)
        .filter(lambda x: x[1] == distance)
        .map(operator.itemgetter(0))
        .to_set()
    )
    neighbours_at_distance = self._handle_center(
        index,
        distance,
        neighbours_at_distance,
        at_distance=True,
        include_center_override=include_center,
    )
    return neighbours_at_distance