chore: Make H3Neighbourhood return only regions under analysis

examples/neighbourhoods/h3_neighbourhood.ipynb

@@ -0,0 +1,221 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from srai.neighbourhoods import H3Neighbourhood\n",
+    "import osmnx as ox\n",
+    "from srai.regionizers import H3Regionizer"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import geopandas as gpd\n",
+    "from typing import Set, Optional\n",
+    "\n",
+    "\n",
+    "def show_neighbours(\n",
+    "    regions_gdf: gpd.GeoDataFrame, region_id: str, neighbours_ids: Optional[Set[str]] = None\n",
+    "):\n",
+    "    regions = regions_gdf.copy()\n",
+    "    regions[\"type\"] = \"none\"\n",
+    "    regions.loc[region_id, \"type\"] = \"region\"\n",
+    "    if neighbours_ids is not None:\n",
+    "        regions.loc[list(neighbours_ids), \"type\"] = \"neighbour\"\n",
+    "    return regions.explore(tiles=\"CartoDB positron\", column=\"type\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf_sf = ox.geocode_to_gdf(\"Wrocław, PL\")\n",
+    "regions_gdf = H3Regionizer(8).transform(gdf_sf)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Region somewhere in the middle of the area under analysis"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Direct neighbours"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "neighbourhood_with_regions = H3Neighbourhood(regions_gdf)\n",
+    "region_id = \"881e204089fffff\"\n",
+    "neighbours_ids = neighbourhood_with_regions.get_neighbours(region_id)\n",
+    "show_neighbours(regions_gdf, region_id, neighbours_ids)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Only 3rd ring"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "neighbours_ids = neighbourhood_with_regions.get_neighbours_at_distance(region_id, 3)\n",
+    "show_neighbours(regions_gdf, region_id, neighbours_ids)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Regions up to distance 3"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "neighbours_ids = neighbourhood_with_regions.get_neighbours_up_to_distance(region_id, 3)\n",
+    "show_neighbours(regions_gdf, region_id, neighbours_ids)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Edge region"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The Neighbourhood only returns the indices of available regions if provided with regions_gdf"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "edge_region_id = \"881e2050bdfffff\"\n",
+    "neighbours_ids = neighbourhood_with_regions.get_neighbours(edge_region_id)\n",
+    "print(neighbours_ids)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "show_neighbours(regions_gdf, edge_region_id, neighbours_ids)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "On the other hand, an \"unbiased\" H3Neighbourhood returns all 6 neighbours from H3."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "neighbourhood_without_regions = H3Neighbourhood()\n",
+    "neighbourhood_without_regions.get_neighbours(edge_region_id)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Regions with a gap"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "One thing to note when using the H3Neighbourhood is that it uses the h3 library under the hood. The only post-processing step is to select from among the regions under analysis. Due to that some neighbours can be included as K-th neighbours, even if there is no path of length K between them and the regions you ask for. This is because H3 still treats them as a part of the K-th ring. An example is shown below"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "edge_region_id = \"881e2050bdfffff\"\n",
+    "neighbours_ids = neighbourhood_with_regions.get_neighbours_at_distance(edge_region_id, 2)\n",
+    "print(neighbours_ids)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "show_neighbours(regions_gdf, edge_region_id, neighbours_ids)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.16"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}