refactor: remove utils module (#128) (#319)

* refactor: remove _optional module from utils * refactor: remove _typing module from utils * refactor: remove download module from utils * refactor: remove geocode module from utils * refactor: remove _pytorch_stubs module from utils * refactor: move merge module to geometry * refactor: remove geometry module from utils * chore: changed changelog * feat: add h3 helper module * refactor: simplified imports after merge * refactor: apply refurb suggestion * chore: add docstrings and change H3Regionalizer * chore: add h3 tests files * chore: change iterable import * test: add h3 ij tests * test: added new tests for h3 module * chore: add future issue comments * chore: fix macos h3ronpy error
kraina-ai · Aug 7, 2023 · 325c556 · 325c556
1 parent 3acc7a6
commit 325c556
Show file tree

Hide file tree

Showing 62 changed files with 699 additions and 167 deletions.
diff --git a/.github/workflows/_tests.yml b/.github/workflows/_tests.yml
@@ -8,10 +8,10 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         include:
           - os: macos-latest
-            python-version: "3.10"
+            python-version: "3.11"
     env:
       OS: ${{ matrix.os }}
       PYTHON: ${{ matrix.python-version }}

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,14 +10,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `include_center` parameter to Neighbourhoods [#288](https://github.com/srai-lab/srai/issues/288)
 
-- Added `__version__` entry to library API. [#305](https://github.com/srai-lab/srai/issues/305)
+- `__version__` entry to library API. [#305](https://github.com/srai-lab/srai/issues/305)
+- `srai.h3` module with functions for translating list of h3 cells into shapely polygons and calculating local ij coordinates.
 
 ### Changed
 
 - Refactored H3Regionalizer to be faster using [h3ronpy](https://github.com/nmandery/h3ronpy) library [#311](https://github.com/srai-lab/srai/issues/311)
 - BREAKING! Renamed NetworkType to OSMNetworkType and made it importable directly from `srai.loaders` [#227](https://github.com/srai-lab/srai/issues/227)
 - BREAKING! Renamed osm_filter_type and grouped_osm_filter_type into OsmTagsFilter and GroupedOsmTagsFilter [#261](https://github.com/srai-lab/srai/issues/261)
 - Removed osmnx dependency version cap [#303](https://github.com/srai-lab/srai/issues/303)
+- BREAKING! Removed `utils` module [#128](https://github.com/srai-lab/srai/issues/128)
+  - `srai.utils._optional` moved to `srai._optional`
+  - `srai.utils._pytorch_stubs` moved to `srai.embedders._pytorch_stubs`
+  - `srai.utils.download` moved to `srai.loaders.download` (and can be imported with `from srai.loaders import download_file`)
+  - `srai.utils.geocode` moved to `srai.regionalizers.geocode` (and can be imported with `from srai.regionalizers import geocode_to_region_gdf`)
+  - `srai.utils.geometry` and `srai.utils.merge` moved to `srai.geometry`
+  - `srai.utils.typing` moved to `srai._typing`
 
 ### Deprecated
 

diff --git a/README.md b/README.md
@@ -97,8 +97,8 @@ Example with `OSMOnlineLoader`:
 
 ```python
 from srai.loaders import OSMOnlineLoader
-from srai.utils import geocode_to_region_gdf
 from srai.plotting import plot_regions
+from srai.regionalizers import geocode_to_region_gdf
 
 query = {"leisure": "park"}
 area = geocode_to_region_gdf("Wrocław, Poland")
@@ -119,8 +119,8 @@ Road network downloading is a special case of OSM data downloading. To download
 
 ```python
 from srai.loaders import OSMNetworkType, OSMWayLoader
-from srai.utils import geocode_to_region_gdf
 from srai.plotting import plot_regions
+from srai.regionalizers import geocode_to_region_gdf
 
 area = geocode_to_region_gdf("Utrecht, Netherlands")
 loader = OSMWayLoader(OSMNetworkType.BIKE)
@@ -142,9 +142,9 @@ To extract features from GTFS use `GTFSLoader`. It will extract trip count and a
 ```python
 from pathlib import Path
 
-from srai.loaders import GTFSLoader
-from srai.utils import geocode_to_region_gdf, download_file
+from srai.loaders import GTFSLoader, download_file
 from srai.plotting import plot_regions
+from srai.regionalizers import geocode_to_region_gdf
 
 area = geocode_to_region_gdf("Vienna, Austria")
 gtfs_file = Path("vienna_gtfs.zip")
@@ -173,8 +173,7 @@ Regionalization is a process of dividing a given area into smaller regions. This
 Example:
 
 ```python
-from srai.regionalizers import H3Regionalizer
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf
 
 area = geocode_to_region_gdf("Berlin, Germany")
 regionalizer = H3Regionalizer(resolution=7)
@@ -206,8 +205,7 @@ from srai.embedders import CountEmbedder
 from srai.joiners import IntersectionJoiner
 from srai.loaders import OSMOnlineLoader
 from srai.plotting import plot_regions, plot_numeric_data
-from srai.regionalizers import H3Regionalizer
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf
 
 loader = OSMOnlineLoader()
 regionalizer = H3Regionalizer(resolution=9)
@@ -238,8 +236,7 @@ from srai.joiners import IntersectionJoiner
 from srai.loaders import OSMPbfLoader
 from srai.loaders.osm_loaders.filters import HEX2VEC_FILTER
 from srai.neighbourhoods.h3_neighbourhood import H3Neighbourhood
-from srai.regionalizers import H3Regionalizer
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf
 from srai.plotting import plot_regions, plot_numeric_data
 
 loader = OSMPbfLoader()

diff --git a/docs/README.md b/docs/README.md
@@ -97,7 +97,7 @@ Example with `OSMOnlineLoader`:
 
 ```python
 from srai.loaders import OSMOnlineLoader
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import geocode_to_region_gdf
 from srai.plotting import plot_regions
 
 query = {"leisure": "park"}
@@ -119,7 +119,7 @@ Road network downloading is a special case of OSM data downloading. To download
 
 ```python
 from srai.loaders import OSMNetworkType, OSMWayLoader
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import geocode_to_region_gdf
 from srai.plotting import plot_regions
 
 area = geocode_to_region_gdf("Utrecht, Netherlands")
@@ -142,8 +142,8 @@ To extract features from GTFS use `GTFSLoader`. It will extract trip count and a
 ```python
 from pathlib import Path
 
-from srai.loaders import GTFSLoader
-from srai.utils import geocode_to_region_gdf, download_file
+from srai.loaders import GTFSLoader, download_file
+from srai.regionalizers import geocode_to_region_gdf
 from srai.plotting import plot_regions
 
 area = geocode_to_region_gdf("Vienna, Austria")
@@ -173,8 +173,7 @@ Regionalization is a process of dividing a given area into smaller regions. This
 Example:
 
 ```python
-from srai.regionalizers import H3Regionalizer
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf
 
 area = geocode_to_region_gdf("Berlin, Germany")
 regionalizer = H3Regionalizer(resolution=7)
@@ -206,8 +205,7 @@ from srai.embedders import CountEmbedder
 from srai.joiners import IntersectionJoiner
 from srai.loaders import OSMOnlineLoader
 from srai.plotting import plot_regions, plot_numeric_data
-from srai.regionalizers import H3Regionalizer
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf
 
 loader = OSMOnlineLoader()
 regionalizer = H3Regionalizer(resolution=9)
@@ -238,8 +236,7 @@ from srai.joiners import IntersectionJoiner
 from srai.loaders import OSMPbfLoader
 from srai.loaders.osm_loaders.filters import HEX2VEC_FILTER
 from srai.neighbourhoods.h3_neighbourhood import H3Neighbourhood
-from srai.regionalizers import H3Regionalizer
-from srai.utils import geocode_to_region_gdf
+from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf
 from srai.plotting import plot_regions, plot_numeric_data
 
 loader = OSMPbfLoader()

diff --git a/examples/embedders/contextual_count_embedder.ipynb b/examples/embedders/contextual_count_embedder.ipynb
@@ -32,7 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from srai.utils import geocode_to_region_gdf\n",
+    "from srai.regionalizers import geocode_to_region_gdf\n",
     "\n",
     "area_gdf = geocode_to_region_gdf(\"Lisboa, PT\")\n",
     "plot_regions(area_gdf)"

diff --git a/examples/embedders/hex2vec_embedder.ipynb b/examples/embedders/hex2vec_embedder.ipynb
@@ -10,8 +10,7 @@
     "from srai.joiners import IntersectionJoiner\n",
     "from srai.loaders import OSMOnlineLoader\n",
     "from srai.neighbourhoods import H3Neighbourhood\n",
-    "from srai.regionalizers import H3Regionalizer\n",
-    "from srai.utils import geocode_to_region_gdf\n",
+    "from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf\n",
     "from srai.plotting import plot_regions, plot_numeric_data\n",
     "from pytorch_lightning import seed_everything"
    ]

diff --git a/examples/embedders/highway2vec_embedder.ipynb b/examples/embedders/highway2vec_embedder.ipynb
@@ -32,7 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from srai.utils import geocode_to_region_gdf\n",
+    "from srai.regionalizers import geocode_to_region_gdf\n",
     "\n",
     "area_gdf = geocode_to_region_gdf(\"Wrocław, PL\")\n",
     "plot_regions(area_gdf, tiles_style=\"CartoDB positron\")"

diff --git a/examples/embedders/load_and_save.ipynb b/examples/embedders/load_and_save.ipynb
@@ -10,8 +10,7 @@
     "from srai.joiners import IntersectionJoiner\n",
     "from srai.loaders import OSMOnlineLoader\n",
     "from srai.neighbourhoods import H3Neighbourhood\n",
-    "from srai.regionalizers import H3Regionalizer\n",
-    "from srai.utils import geocode_to_region_gdf\n",
+    "from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf\n",
     "from srai.plotting import plot_regions, plot_numeric_data\n",
     "from pytorch_lightning import seed_everything"
    ]

diff --git a/examples/loaders/gtfs_loader.ipynb b/examples/loaders/gtfs_loader.ipynb
@@ -15,12 +15,11 @@
    "outputs": [],
    "source": [
     "from pathlib import Path\n",
-    "from srai.loaders import GTFSLoader\n",
+    "from srai.loaders import GTFSLoader, download_file\n",
     "import gtfs_kit as gk\n",
     "import geopandas as gpd\n",
     "from shapely.geometry import Point\n",
-    "from srai.constants import WGS84_CRS\n",
-    "from srai.utils import download_file"
+    "from srai.constants import WGS84_CRS"
    ]
   },
   {

diff --git a/examples/loaders/osm_online_loader.ipynb b/examples/loaders/osm_online_loader.ipynb
@@ -17,7 +17,7 @@
     "from srai.loaders.osm_loaders.filters.popular import get_popular_tags\n",
     "from srai.loaders.osm_loaders.filters import GEOFABRIK_LAYERS, HEX2VEC_FILTER\n",
     "from srai.loaders.osm_loaders import OSMOnlineLoader\n",
-    "from srai.utils import geocode_to_region_gdf\n",
+    "from srai.regionalizers import geocode_to_region_gdf\n",
     "from srai.plotting.folium_wrapper import plot_regions\n",
     "from functional import seq"
    ]

diff --git a/examples/loaders/osm_pbf_loader.ipynb b/examples/loaders/osm_pbf_loader.ipynb
@@ -24,7 +24,8 @@
     "from srai.loaders.osm_loaders.filters.popular import get_popular_tags\n",
     "from srai.loaders.osm_loaders import OSMPbfLoader\n",
     "from srai.constants import REGIONS_INDEX, WGS84_CRS\n",
-    "from srai.utils import buffer_geometry, geocode_to_region_gdf\n",
+    "from srai.regionalizers import geocode_to_region_gdf\n",
+    "from srai.geometry import buffer_geometry\n",
     "\n",
     "from shapely.geometry import Point, box\n",
     "import geopandas as gpd"

diff --git a/examples/loaders/osm_tile_loader.ipynb b/examples/loaders/osm_tile_loader.ipynb
@@ -15,7 +15,7 @@
    "outputs": [],
    "source": [
     "from srai.loaders.osm_loaders import OSMTileLoader\n",
-    "from srai.utils import geocode_to_region_gdf\n",
+    "from srai.regionalizers import geocode_to_region_gdf\n",
     "\n",
     "ZOOM = 9"
    ]

diff --git a/examples/loaders/osm_way_loader.ipynb b/examples/loaders/osm_way_loader.ipynb
@@ -20,7 +20,7 @@
     "from srai.loaders import OSMNetworkType, OSMWayLoader\n",
     "from srai.constants import WGS84_CRS, REGIONS_INDEX\n",
     "from srai.plotting.folium_wrapper import plot_regions\n",
-    "from srai.utils import geocode_to_region_gdf"
+    "from srai.regionalizers import geocode_to_region_gdf"
    ]
   },
   {

diff --git a/examples/neighbourhoods/adjacency_neighbourhood.ipynb b/examples/neighbourhoods/adjacency_neighbourhood.ipynb
@@ -12,8 +12,11 @@
     "\n",
     "from srai.constants import WGS84_CRS\n",
     "from srai.neighbourhoods import AdjacencyNeighbourhood\n",
-    "from srai.regionalizers import AdministrativeBoundaryRegionalizer, VoronoiRegionalizer\n",
-    "from srai.utils.geocode import geocode_to_region_gdf\n",
+    "from srai.regionalizers import (\n",
+    "    AdministrativeBoundaryRegionalizer,\n",
+    "    VoronoiRegionalizer,\n",
+    "    geocode_to_region_gdf,\n",
+    ")\n",
     "from srai.plotting.folium_wrapper import plot_regions, plot_neighbours, plot_all_neighbourhood"
    ]
   },

diff --git a/examples/neighbourhoods/h3_neighbourhood.ipynb b/examples/neighbourhoods/h3_neighbourhood.ipynb
@@ -7,8 +7,7 @@
    "outputs": [],
    "source": [
     "from srai.neighbourhoods import H3Neighbourhood\n",
-    "from srai.regionalizers import H3Regionalizer\n",
-    "from srai.utils.geocode import geocode_to_region_gdf\n",
+    "from srai.regionalizers import H3Regionalizer, geocode_to_region_gdf\n",
     "from srai.plotting.folium_wrapper import plot_neighbours, plot_all_neighbourhood"
    ]
   },

diff --git a/examples/regionalizers/administrative_boundary_regionalizer.ipynb b/examples/regionalizers/administrative_boundary_regionalizer.ipynb
@@ -10,9 +10,8 @@
     "import plotly.express as px\n",
     "from shapely.geometry import Point, box\n",
     "\n",
-    "from srai.regionalizers import AdministrativeBoundaryRegionalizer\n",
-    "from srai.plotting.folium_wrapper import plot_regions\n",
-    "from srai.utils import geocode_to_region_gdf"
+    "from srai.regionalizers import AdministrativeBoundaryRegionalizer, geocode_to_region_gdf\n",
+    "from srai.plotting.folium_wrapper import plot_regions"
    ]
   },
   {

diff --git a/examples/regionalizers/voronoi_regionalizer.ipynb b/examples/regionalizers/voronoi_regionalizer.ipynb
@@ -11,10 +11,9 @@
     "import plotly.express as px\n",
     "from shapely.geometry import Point\n",
     "\n",
-    "from srai.regionalizers import VoronoiRegionalizer\n",
+    "from srai.regionalizers import VoronoiRegionalizer, geocode_to_region_gdf\n",
     "from srai.constants import WGS84_CRS\n",
-    "from srai.plotting.folium_wrapper import plot_regions\n",
-    "from srai.utils import geocode_to_region_gdf"
+    "from srai.plotting.folium_wrapper import plot_regions"
    ]
   },
   {

diff --git a/pdm.lock b/pdm.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ dependencies = [
     "s2",
     "typeguard",
     "requests",
-    "h3ronpy",
+    "h3ronpy>=0.17.4",
 ]
 requires-python = ">=3.8"
 readme = "README.md"
@@ -59,12 +59,7 @@ Changelog = "https://github.com/srai-lab/srai/blob/main/CHANGELOG.md"
 # add tests
 
 # pdm add -G osm <library>
-osm = [
-    "osmium",
-    "osmnx",
-    "overpass",
-    "pillow",
-]
+osm = ["osmium", "osmnx", "overpass", "pillow"]
 # pdm add -G voronoi <library>
 voronoi = ["pymap3d", "haversine", "scipy", "spherical-geometry"]
 # pdm add -G gtfs <library>

diff --git a/srai/utils/_optional.py → srai/_optional.py b/srai/utils/_optional.py → srai/_optional.py
diff --git a/srai/utils/typing.py → srai/_typing.py b/srai/utils/typing.py → srai/_typing.py
diff --git a/srai/embedders/_base.py b/srai/embedders/_base.py
@@ -13,7 +13,7 @@
     from pytorch_lightning import LightningModule
 
 except ImportError:
-    from srai.utils._pytorch_stubs import LightningModule
+    from srai.embedders._pytorch_stubs import LightningModule
 
 
 class Model(LightningModule):  # type: ignore

diff --git a/srai/utils/_pytorch_stubs.py → srai/embedders/_pytorch_stubs.py b/srai/utils/_pytorch_stubs.py → srai/embedders/_pytorch_stubs.py
diff --git a/srai/embedders/gtfs2vec/embedder.py b/srai/embedders/gtfs2vec/embedder.py
@@ -17,11 +17,11 @@
 import numpy as np
 import pandas as pd
 
+from srai._optional import import_optional_dependencies
 from srai.embedders import Embedder, ModelT
 from srai.embedders.gtfs2vec.model import GTFS2VecModel
 from srai.exceptions import ModelNotFitException
 from srai.loaders.gtfs_loader import GTFS2VEC_DIRECTIONS_PREFIX, GTFS2VEC_TRIPS_PREFIX
-from srai.utils._optional import import_optional_dependencies
 
 
 class GTFS2VecEmbedder(Embedder):

diff --git a/srai/embedders/gtfs2vec/model.py b/srai/embedders/gtfs2vec/model.py
@@ -8,8 +8,8 @@
 """
 from typing import TYPE_CHECKING, Any
 
+from srai._optional import import_optional_dependencies
 from srai.embedders import Model
-from srai.utils._optional import import_optional_dependencies
 
 if TYPE_CHECKING:  # pragma: no cover
     import torch