feat: add basic plotting functions to the library

.github/workflows/ci-dev.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: "3.10"
       - name: Install required osmium dependencies
         run: sudo apt-get install build-essential cmake libboost-dev libexpat1-dev zlib1g-dev libbz2-dev
       - uses: actions/cache@v3
@@ -72,8 +72,6 @@ jobs:
         run: pdm export --no-default -G docs -G visualization -f requirements -o requirements.txt
       - name: Install dependencies
         run: pip install --no-deps -r requirements.txt
-      - name: Install geovoronoi dependency
-        run: pip install geovoronoi==0.4.0
       - name: Install nbconvert dependency
         run: pip install jupyter nbconvert nbformat
       - name: Install srai

.github/workflows/ci-prod.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.10'
+          python-version: "3.10"
       - name: Install required osmium dependencies
         run: sudo apt-get install build-essential cmake libboost-dev libexpat1-dev zlib1g-dev libbz2-dev
       - uses: actions/cache@v3
@@ -58,8 +58,6 @@ jobs:
         run: pdm export --no-default -G docs -G visualization -f requirements -o requirements.txt
       - name: Install dependencies
         run: pip install --no-deps -r requirements.txt
-      - name: Install geovoronoi dependency
-        run: pip install geovoronoi==0.4.0
       - name: Install nbconvert dependency
         run: pip install jupyter nbconvert nbformat
       - name: Install srai

CHANGELOG.md

@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - H3Neighbourhood
 - AdjacencyNeighbourhood
 - (CI) Changelog Enforcer
+- Utility plotting module based on Folium and Plotly
 
 ### Changed
 

codecov.yml

@@ -4,10 +4,13 @@ coverage:
       default:
         target: auto
         informational: true
-        threshold: 1%  # the leniency in hitting the target
+        threshold: 1% # the leniency in hitting the target
     patch:
       default:
         informational: true
 
 comment:
   require_changes: true
+
+ignore:
+  - "srai/plotting" # disable coverage for plotting module

examples/embedders/count_embedder.ipynb

@@ -8,11 +8,12 @@
    "source": [
     "from shapely import geometry\n",
     "import geopandas as gpd\n",
-    "from srai.constants import WGS84_CRS\n",
+    "from srai.constants import WGS84_CRS, REGIONS_INDEX\n",
     "from srai.loaders.osm_loaders import OSMOnlineLoader\n",
     "from srai.regionizers import H3Regionizer\n",
     "from srai.joiners import IntersectionJoiner\n",
-    "from srai.embedders import CountEmbedder"
+    "from srai.embedders import CountEmbedder\n",
+    "from srai.plotting.folium_wrapper import plot_regions, plot_numeric_data"
    ]
   },
   {
@@ -75,8 +76,8 @@
    "source": [
     "regionizer = H3Regionizer(resolution=8, buffer=True)\n",
     "regions_gdf = regionizer.transform(bbox_gdf)\n",
-    "ax = bbox_gdf.plot()\n",
-    "regions_gdf.plot(ax=ax, color=\"red\", alpha=0.5)"
+    "folium_map = bbox_gdf.explore(tiles=\"CartoDB positron\")\n",
+    "plot_regions(regions_gdf, map=folium_map)"
    ]
   },
   {
@@ -108,11 +109,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ax = regions_gdf.plot()\n",
-    "features_gdf.plot(\n",
-    "    ax=ax,\n",
-    "    color=\"red\",\n",
-    ")"
+    "folium_map = plot_regions(regions_gdf, tiles_style=\"CartoDB positron\", colormap=[\"lightgray\"])\n",
+    "features_gdf.explore(m=folium_map)"
    ]
   },
   {
@@ -140,7 +138,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "joint_gdf.plot()"
+    "from plotly.express import colors\n",
+    "\n",
+    "folium_map = plot_regions(regions_gdf, tiles_style=\"CartoDB positron\", colormap=[\"rgba(0,0,0,0)\"])\n",
+    "joint_gdf.reset_index().explore(m=folium_map, column=REGIONS_INDEX, cmap=colors.qualitative.Bold)"
    ]
   },
   {
@@ -181,6 +182,17 @@
     "embedding_expected_features"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot_numeric_data(\n",
+    "    regions_gdf, embedding_expected_features, \"amenity_pub\", tiles_style=\"CartoDB positron\"\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -208,7 +220,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.16"
+   "version": "3.8.10"
   },
   "vscode": {
    "interpreter": {

examples/embedders/gtfs2vec_embedder.ipynb

@@ -6,11 +6,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from srai.embedders import GTFS2VecEmbedder\n",
     "import pandas as pd\n",
-    "from shapely.geometry import Polygon\n",
     "import geopandas as gpd\n",
-    "from pytorch_lightning import seed_everything"
+    "from shapely.geometry import Polygon\n",
+    "from pytorch_lightning import seed_everything\n",
+    "\n",
+    "from srai.embedders import GTFS2VecEmbedder\n",
+    "from srai.constants import REGIONS_INDEX"
    ]
   },
   {
@@ -47,9 +49,8 @@
     "        ],\n",
     "    },\n",
     "    geometry=gpd.points_from_xy([1, 2, 5], [1, 2, 2]),\n",
-    "    index=[1, 2, 3],\n",
+    "    index=pd.Index(name=\"stop_id\", data=[1, 2, 3]),\n",
     ")\n",
-    "features_gdf.index.name = \"stop_id\"\n",
     "features_gdf"
    ]
   },
@@ -60,18 +61,23 @@
    "outputs": [],
    "source": [
     "regions_gdf = gpd.GeoDataFrame(\n",
-    "    {\n",
-    "        \"region_id\": [\"ff1\", \"ff2\", \"ff3\"],\n",
-    "    },\n",
     "    geometry=[\n",
     "        Polygon([(0, 0), (0, 3), (3, 3), (3, 0)]),\n",
     "        Polygon([(4, 0), (4, 3), (7, 3), (7, 0)]),\n",
     "        Polygon([(8, 0), (8, 3), (11, 3), (11, 0)]),\n",
     "    ],\n",
-    ").set_index(\"region_id\")\n",
+    "    index=pd.Index(name=REGIONS_INDEX, data=[\"ff1\", \"ff2\", \"ff3\"]),\n",
+    ")\n",
     "regions_gdf"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -91,7 +97,7 @@
     "joint_gdf = gpd.GeoDataFrame()\n",
     "joint_gdf.index = pd.MultiIndex.from_tuples(\n",
     "    [(\"ff1\", 1), (\"ff1\", 2), (\"ff2\", 3)],\n",
-    "    names=[\"region_id\", \"stop_id\"],\n",
+    "    names=[REGIONS_INDEX, \"stop_id\"],\n",
     ")\n",
     "joint_gdf"
    ]
@@ -153,7 +159,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.14"
+   "version": "3.8.10"
   },
   "vscode": {
    "interpreter": {

examples/joiners/intersection_joiner.ipynb

@@ -8,7 +8,9 @@
    "source": [
     "import geopandas as gpd\n",
     "from shapely import geometry\n",
-    "import matplotlib.pyplot as plt"
+    "import matplotlib.pyplot as plt\n",
+    "from srai.constants import WGS84_CRS, REGIONS_INDEX, FEATURES_INDEX\n",
+    "from srai.plotting.folium_wrapper import plot_regions"
    ]
   },
   {
@@ -32,7 +34,8 @@
     "        geometry.Polygon([(-2, -1), (-2, -2), (-1, -2), (-1, -1)]),\n",
     "        geometry.Polygon([(-2, 0.5), (-2, -0.5), (-1, -0.5), (-1, 0.5)]),\n",
     "    ],\n",
-    "    crs=\"epsg:4326\",\n",
+    "    crs=WGS84_CRS,\n",
+    "    index=gpd.pd.Index(name=REGIONS_INDEX, data=[1, 2, 3, 4]),\n",
     ")\n",
     "\n",
     "features = gpd.GeoDataFrame(\n",
@@ -42,15 +45,41 @@
     "        geometry.Point((0, 0)),\n",
     "        geometry.Point((-0.5, -0.5)),\n",
     "    ],\n",
-    "    crs=\"epsg:4326\",\n",
-    ")\n",
-    "\n",
-    "print(regions)\n",
-    "print(features)\n",
-    "\n",
-    "ax = regions.plot()\n",
-    "features.plot(ax=ax, color=\"red\", alpha=0.5)\n",
-    "plt.show()"
+    "    crs=WGS84_CRS,\n",
+    "    index=gpd.pd.Index(name=FEATURES_INDEX, data=[1, 2, 3, 4]),\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "regions"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "features"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "folium_map = plot_regions(regions, colormap=[\"royalblue\"])\n",
+    "features.explore(\n",
+    "    m=folium_map,\n",
+    "    style_kwds=dict(color=\"red\", opacity=0.8, fillColor=\"red\", fillOpacity=0.5),\n",
+    "    marker_kwds=dict(radius=3),\n",
+    ")"
    ]
   },
   {
@@ -72,13 +101,26 @@
     "joiner = IntersectionJoiner()\n",
     "joint = joiner.transform(regions, features)\n",
     "\n",
-    "print(joint)\n",
-    "\n",
-    "ax = regions.plot(alpha=0.3)\n",
-    "ax = features.plot(ax=ax, color=\"red\", alpha=0.3)\n",
-    "joint.plot(ax=ax, color=\"green\", alpha=0.5)\n",
-    "\n",
-    "plt.show()"
+    "joint"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "folium_map = plot_regions(regions, colormap=[\"royalblue\"])\n",
+    "features.explore(\n",
+    "    m=folium_map,\n",
+    "    style_kwds=dict(color=\"red\", opacity=0.5, fillColor=\"red\", fillOpacity=0.5),\n",
+    "    marker_kwds=dict(radius=3),\n",
+    ")\n",
+    "joint.explore(\n",
+    "    m=folium_map,\n",
+    "    style_kwds=dict(color=\"yellow\", opacity=1.0, fillColor=\"yellow\", fillOpacity=1.0),\n",
+    "    marker_kwds=dict(radius=3),\n",
+    ")"
    ]
   }
  ],
@@ -98,7 +140,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.14"
+   "version": "3.8.10"
   },
   "vscode": {
    "interpreter": {

examples/loaders/geoparquet_loader.ipynb

@@ -6,12 +6,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pathlib import Path\n",
-    "\n",
     "import geopandas as gpd\n",
     "from shapely.geometry import box\n",
     "\n",
-    "from srai.loaders import GeoparquetLoader"
+    "from srai.loaders import GeoparquetLoader\n",
+    "from srai.constants import WGS84_CRS"
    ]
   },
   {
@@ -46,7 +45,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "base_gdf.plot()"
+    "base_gdf.explore()"
    ]
   },
   {
@@ -79,7 +78,7 @@
    "source": [
     "# Create Texas bounding box\n",
     "bbox = box(minx=-106.645646, maxx=-93.508292, miny=25.837377, maxy=36.500704)\n",
-    "bbox_gdf = gpd.GeoDataFrame({\"geometry\": [bbox]}, crs=\"EPSG:4326\")\n",
+    "bbox_gdf = gpd.GeoDataFrame({\"geometry\": [bbox]}, crs=WGS84_CRS)\n",
     "\n",
     "cut_gdf = gpql.load(file_path=\"example_files/example.parquet\", area=bbox_gdf)\n",
     "cut_gdf"
@@ -91,7 +90,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "cut_gdf.plot()"
+    "cut_gdf.explore()"
    ]
   }
  ],
@@ -111,7 +110,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.14"
+   "version": "3.8.10"
   },
   "vscode": {
    "interpreter": {