ssb-sgis 1.0.1__py3-none-any.whl → 1.0.2__py3-none-any.whl

sgis/geopandas_tools/polygons_as_rings.py

@@ -1,59 +1,26 @@
-from typing import Any, Callable, Iterable
+from collections.abc import Callable
+from typing import Any
 
-import geopandas as gpd
-import igraph
-import networkx as nx
 import numpy as np
 import pandas as pd
-from geopandas import GeoDataFrame, GeoSeries
+from geopandas import GeoDataFrame
+from geopandas import GeoSeries
 from geopandas.array import GeometryArray
-from IPython.display import display
-from networkx.algorithms import approximation as approx
-from numpy import ndarray
 from numpy.typing import NDArray
-from pandas import Index
-from shapely import (
-    Geometry,
-    STRtree,
-    area,
-    box,
-    buffer,
-    centroid,
-    difference,
-    distance,
-    extract_unique_points,
-    get_coordinates,
-    get_exterior_ring,
-    get_interior_ring,
-    get_num_interior_rings,
-    get_parts,
-    intersection,
-    intersects,
-    is_empty,
-    is_ring,
-    length,
-    line_merge,
-    linearrings,
-    linestrings,
-    make_valid,
-    points,
-    polygons,
-    segmentize,
-    simplify,
-    unary_union,
-    voronoi_polygons,
-)
-from shapely.errors import GEOSException
-from shapely.geometry import (
-    LinearRing,
-    LineString,
-    MultiLineString,
-    MultiPoint,
-    Point,
-    Polygon,
-)
-
-from .conversion import to_gdf, to_geoseries
+from pyproj import CRS
+from shapely import get_coordinates
+from shapely import get_exterior_ring
+from shapely import get_interior_ring
+from shapely import get_num_interior_rings
+from shapely import linearrings
+from shapely import make_valid
+from shapely import polygons
+from shapely import unary_union
+from shapely.geometry import LinearRing
+from shapely.geometry import Polygon
+
+from .conversion import to_gdf
+from .conversion import to_geoseries
 
 
 class PolygonsAsRings:
@@ -62,10 +29,18 @@ class PolygonsAsRings:
     def __init__(
         self,
         polys: GeoDataFrame | GeoSeries | GeometryArray,
-        crs=None,
+        crs: CRS | Any | None = None,
         allow_multipart: bool = False,
         gridsize: int | None = None,
-    ):
+    ) -> None:
+        """Initialize the PolygonsAsRings object with polygons and optional CRS information.
+
+        Args:
+            polys: GeoDataFrame, GeoSeries, or GeometryArray containing polygon geometries.
+            crs: Coordinate Reference System to be used, defaults to None.
+            allow_multipart: Allow multipart polygons if True, defaults to False.
+            gridsize: Size of the grid for any grid operations, defaults to None.
+        """
         if not isinstance(polys, (pd.DataFrame, pd.Series, GeometryArray)):
             raise TypeError(type(polys))
 
@@ -125,7 +100,16 @@ class PolygonsAsRings:
 
         self.rings = pd.concat([exterior, interiors])
 
-    def get_rings(self, agg: bool = False):
+    def get_rings(self, agg: bool = False) -> GeoDataFrame | GeoSeries | np.ndarray:
+        """Retrieve rings from the polygons, optionally aggregating them.
+
+        Args:
+            agg: If True, aggregate the rings into single geometries.
+
+        Returns:
+            The rings either aggregated or separated, in the type of
+                the input polygons.
+        """
         gdf = self.gdf.copy()
         rings = self.rings.copy()
         if not len(rings):
@@ -144,9 +128,21 @@ class PolygonsAsRings:
         return self.polyclass(gdf.geometry.values)
 
     def apply_numpy_func_to_interiors(
-        self, func: Callable, args: tuple | None = None, kwargs: dict | None = None
-    ):
-        """Run an array function on only the interior rings of the polygons."""
+        self,
+        func: Callable,
+        args: tuple | None = None,
+        kwargs: dict | None = None,
+    ) -> "PolygonsAsRings":
+        """Apply a numpy function specifically to the interior rings of the polygons.
+
+        Args:
+            func: Numpy function to apply.
+            args: Tuple of positional arguments for the function.
+            kwargs: Dictionary of keyword arguments for the function.
+
+        Returns:
+            PolygonsAsRings: The instance itself after applying the function.
+        """
         kwargs = kwargs or {}
         args = args or ()
         arr: NDArray[LinearRing] = self.rings.loc[self.is_interior].values
@@ -159,9 +155,21 @@ class PolygonsAsRings:
         return self
 
     def apply_numpy_func(
-        self, func: Callable, args: tuple | None = None, kwargs: dict | None = None
-    ):
-        """Run a function that takes an array of lines/rings and returns an array of lines/rings."""
+        self,
+        func: Callable,
+        args: tuple | None = None,
+        kwargs: dict | None = None,
+    ) -> "PolygonsAsRings":
+        """Apply a numpy function to all rings of the polygons.
+
+        Args:
+            func: Numpy function to apply.
+            args: Tuple of positional arguments for the function.
+            kwargs: Dictionary of keyword arguments for the function.
+
+        Returns:
+            PolygonsAsRings: The instance itself after applying the function.
+        """
         kwargs = kwargs or {}
         args = args or ()
 
@@ -172,18 +180,30 @@ class PolygonsAsRings:
                 f"Different length of results. Got {len(results)} and {len(self.rings)} original rings"
             )
 
-        self.rings.loc[:] = results
+        self.rings.loc[:] = results  # type: ignore [call-overload]
 
         return self
 
     def apply_geoseries_func(
-        self, func: Callable, args: tuple | None = None, kwargs: dict | None = None
-    ):
-        """Run a function that takes a GeoSeries and returns a GeoSeries."""
+        self,
+        func: Callable,
+        args: tuple | None = None,
+        kwargs: dict | None = None,
+    ) -> "PolygonsAsRings":
+        """Apply a function that operates on a GeoSeries to the rings.
+
+        Args:
+            func: Function to apply that expects a GeoSeries.
+            args: Tuple of positional arguments for the function.
+            kwargs: Dictionary of keyword arguments for the function.
+
+        Returns:
+            PolygonsAsRings: The instance itself after applying the function.
+        """
         kwargs = kwargs or {}
         args = args or ()
 
-        self.rings.loc[:] = np.array(
+        self.rings.loc[:] = np.array(  # type: ignore [call-overload]
             func(
                 GeoSeries(
                     self.rings.values,
@@ -198,9 +218,21 @@ class PolygonsAsRings:
         return self
 
     def apply_gdf_func(
-        self, func: Callable, args: tuple | None = None, kwargs: dict | None = None
-    ):
-        """Run a function that takes a GeoDataFrame and returns a GeoDataFrame."""
+        self,
+        func: Callable,
+        args: tuple | None = None,
+        kwargs: dict | None = None,
+    ) -> "PolygonsAsRings":
+        """Apply a function that operates on a GeoDataFrame to the rings.
+
+        Args:
+            func: Function to apply that expects a GeoDataFrame.
+            args: Tuple of positional arguments for the function.
+            kwargs: Dictionary of keyword arguments for the function.
+
+        Returns:
+            PolygonsAsRings: The instance itself after applying the function.
+        """
         kwargs = kwargs or {}
         args = args or ()
 
@@ -214,7 +246,7 @@ class PolygonsAsRings:
 
         gdf.index = self.rings.index
 
-        self.rings.loc[:] = func(
+        self.rings.loc[:] = func(  # type: ignore [call-overload]
             gdf,
             *args,
             **kwargs,
@@ -223,15 +255,17 @@ class PolygonsAsRings:
         return self
 
     @property
-    def is_interior(self):
+    def is_interior(self) -> bool:
+        """Returns a boolean Series of whether the row is an interior ring."""
         return self.rings.index.get_level_values(0) == 1
 
     @property
-    def is_exterior(self):
+    def is_exterior(self) -> bool:
+        """Returns a boolean Series of whether the row is an exterior ring."""
         return self.rings.index.get_level_values(0) == 0
 
     @property
-    def _interiors_index(self):
+    def _interiors_index(self) -> pd.MultiIndex:
         """A three-leveled MultiIndex.
 
         Used to separate interior and exterior and sort the interior in
@@ -254,7 +288,7 @@ class PolygonsAsRings:
         )
 
     @property
-    def _exterior_index(self):
+    def _exterior_index(self) -> pd.MultiIndex:
         """A three-leveled MultiIndex.
 
         Used to separate interior and exterior in the 'to_numpy' method.
@@ -274,8 +308,8 @@ class PolygonsAsRings:
         self.gdf.geometry = self.to_numpy()
         return self.gdf
 
-    def to_geoseries(self) -> GeoDataFrame:
-        """Return the GeoDataFrame with polygons."""
+    def to_geoseries(self) -> GeoSeries:
+        """Return the GeoSeries with polygons."""
         self.gdf.geometry = self.to_numpy()
         return self.gdf.geometry
 
@@ -293,7 +327,7 @@ class PolygonsAsRings:
             try:
                 return make_valid(polygons(exterior.values))
             except Exception:
-                return _geoms_to_linearrings_fallback(exterior)
+                return _geoms_to_linearrings_fallback(exterior).values
 
         empty_interiors = pd.Series(
             [None for _ in range(len(self.gdf) * self.max_rings)],
@@ -312,10 +346,18 @@ class PolygonsAsRings:
         try:
             return make_valid(polygons(exterior.values, interiors.values))
         except Exception:
-            return _geoms_to_linearrings_fallback(exterior, interiors)
+            return _geoms_to_linearrings_fallback(exterior, interiors).values
+
+
+def get_linearring_series(geoms: GeoDataFrame | GeoSeries) -> pd.Series:
+    """Convert geometries into a series of LinearRings.
 
+    Args:
+        geoms: GeoDataFrame or GeoSeries from which to extract LinearRings.
 
-def get_linearring_series(geoms: Any) -> pd.Series:
+    Returns:
+        pd.Series: A series containing LinearRings.
+    """
     geoms = to_geoseries(geoms).explode(index_parts=False)
     coords, indices = get_coordinates(geoms, return_index=True)
     return pd.Series(linearrings(coords, indices=indices), index=geoms.index)
@@ -325,6 +367,7 @@ def _geoms_to_linearrings_fallback(
     exterior: pd.Series, interiors: pd.Series | None = None
 ) -> pd.Series:
     exterior.index = exterior.index.get_level_values(1)
+    assert exterior.index.is_monotonic_increasing
 
     exterior = get_linearring_series(exterior)
 

sgis/geopandas_tools/sfilter.py

@@ -2,12 +2,12 @@ import warnings
 
 import numpy as np
 import pandas as pd
-from geopandas import GeoDataFrame, GeoSeries
+from geopandas import GeoDataFrame
+from geopandas import GeoSeries
 from shapely import Geometry
 
 from .conversion import to_gdf
 
-
 gdf_type_error_message = "'gdf' should be of type GeoDataFrame or GeoSeries."
 
 
@@ -34,9 +34,9 @@ def sfilter(
         A copy of 'gdf' with only the rows matching the
         spatial predicate with 'other'.
 
-    Examples
+    Examples:
     --------
-
+    >>> import sgis as sg
     >>> df1 = sg.to_gdf([(0, 0), (0, 1)])
     >>> df1
                       geometry
@@ -71,7 +71,7 @@ def sfilter(
     0  POINT (0.00000 0.00000)
 
     """
-    if not isinstance(gdf, (GeoDataFrame, GeoSeries)):
+    if not isinstance(gdf, (GeoDataFrame | GeoSeries)):
         raise TypeError(gdf_type_error_message)
 
     other = _sfilter_checks(other, crs=gdf.crs)
@@ -100,9 +100,9 @@ def sfilter_split(
         A tuple of GeoDataFrames, one with the rows that match the spatial predicate
         and one with the rows that do not.
 
-    Examples
+    Examples:
     --------
-
+    >>> import sgis as sg
     >>> df1 = sg.to_gdf([(0, 0), (0, 1)])
     >>> df1
                       geometry
@@ -140,7 +140,7 @@ def sfilter_split(
     >>> not_intersecting = df1.loc[~filt]
 
     """
-    if not isinstance(gdf, (GeoDataFrame, GeoSeries)):
+    if not isinstance(gdf, (GeoDataFrame | GeoSeries)):
         raise TypeError(gdf_type_error_message)
 
     other = _sfilter_checks(other, crs=gdf.crs)
@@ -149,7 +149,7 @@ def sfilter_split(
 
     return (
         gdf.iloc[indices],
-        gdf.iloc[pd.Index(range(len(gdf))).difference(indices)],
+        gdf.iloc[pd.Index(range(len(gdf))).difference(pd.Index(indices))],
     )
 
 
@@ -171,9 +171,9 @@ def sfilter_inverse(
         A copy of 'gdf' with only the rows that do not match the
         spatial predicate with 'other'.
 
-    Examples
+    Examples:
     --------
-
+    >>> import sgis as sg
     >>> df1 = sg.to_gdf([(0, 0), (0, 1)])
     >>> df1
                       geometry
@@ -205,14 +205,14 @@ def sfilter_inverse(
     >>> not_intersecting = df1.loc[~df1.intersects(df2.unary_union)]
 
     """
-    if not isinstance(gdf, (GeoDataFrame, GeoSeries)):
+    if not isinstance(gdf, (GeoDataFrame | GeoSeries)):
         raise TypeError(gdf_type_error_message)
 
     other = _sfilter_checks(other, crs=gdf.crs)
 
     indices = _get_sfilter_indices(gdf, other, predicate)
 
-    return gdf.iloc[pd.Index(range(len(gdf))).difference(indices)]
+    return gdf.iloc[pd.Index(range(len(gdf))).difference(pd.Index(indices))]
 
 
 def _sfilter_checks(other, crs):
@@ -256,7 +256,7 @@ def _get_sfilter_indices(
     predicate : string
         Binary predicate to query.
 
-    Returns
+    Returns:
     -------
     DataFrame
         DataFrame with matching indices in

sgis/helpers.py

@@ -1,15 +1,29 @@
 """Small helper functions."""
+
 import glob
 import inspect
 import os
 import warnings
 from collections.abc import Callable
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
 
 import numpy as np
+import pandas as pd
 from geopandas import GeoDataFrame
 
 
-def get_numpy_func(text, error_message: str | None = None) -> Callable:
+def get_numpy_func(text: str, error_message: str | None = None) -> Callable:
+    """Fetch a numpy function based on its name.
+
+    Args:
+        text: The name of the numpy function to retrieve.
+        error_message: Custom error message if the function is not found.
+
+    Returns:
+        The numpy function corresponding to the provided text.
+    """
     f = getattr(np, text, None)
     if f is not None:
         return f
@@ -19,20 +33,36 @@ def get_numpy_func(text, error_message: str | None = None) -> Callable:
     raise ValueError(error_message)
 
 
-def get_func_name(func):
+def get_func_name(func: Callable) -> str:
+    """Return the name of a function.
+
+    Args:
+        func: The function object whose name is to be retrieved.
+
+    Returns:
+        The name of the function.
+    """
     try:
         return func.__name__
     except AttributeError:
         return str(func)
 
 
-def get_non_numpy_func_name(f):
+def get_non_numpy_func_name(f: Callable | str) -> str:
     if callable(f):
         return f.__name__
     return str(f).replace("np.", "").replace("numpy.", "")
 
 
-def to_numpy_func(text):
+def to_numpy_func(text: str) -> Callable:
+    """Convert a text identifier into a numpy function.
+
+    Args:
+        text: Name of the numpy function.
+
+    Returns:
+        The numpy function.
+    """
     f = getattr(np, text, None)
     if f is not None:
         return f
@@ -42,13 +72,22 @@ def to_numpy_func(text):
     raise ValueError
 
 
-def is_property(obj, attribute) -> bool:
+def is_property(obj: object, attribute: str) -> bool:
+    """Determine if a class attribute is a property.
+
+    Args:
+        obj: The object to check.
+        attribute: The attribute name to check on the object.
+
+    Returns:
+        True if the attribute is a property, False otherwise.
+    """
     return hasattr(obj.__class__, attribute) and isinstance(
         getattr(obj.__class__, attribute), property
     )
 
 
-def dict_zip_intersection(*dicts):
+def dict_zip_intersection(*dicts: dict) -> Generator[tuple[Any, ...], None, None]:
     """From mCoding (YouTube)."""
     if not dicts:
         return
@@ -58,7 +97,9 @@ def dict_zip_intersection(*dicts):
         yield key, *(d[key] for d in dicts)
 
 
-def dict_zip_union(*dicts, fillvalue=None):
+def dict_zip_union(
+    *dicts: dict, fillvalue: Any | None = None
+) -> Generator[tuple[Any, ...], None, None]:
     """From mCoding (YouTube)."""
     if not dicts:
         return
@@ -68,7 +109,7 @@ def dict_zip_union(*dicts, fillvalue=None):
         yield key, *(d.get(key, fillvalue) for d in dicts)
 
 
-def dict_zip(*dicts):
+def dict_zip(*dicts: dict) -> Generator[tuple[Any, ...], None, None]:
     """From mCoding (YouTube)."""
     if not dicts:
         return
@@ -81,15 +122,24 @@ def dict_zip(*dicts):
         yield key, first_val, *(other[key] for other in dicts[1:])
 
 
-def in_jupyter():
+def in_jupyter() -> bool:
     try:
-        get_ipython
+        get_ipython  # type: ignore[name-defined]
         return True
     except NameError:
         return False
 
 
-def get_all_files(root, recursive=True):
+def get_all_files(root: str, recursive: bool = True) -> list[str]:
+    """Fetch all files in a directory.
+
+    Args:
+        root: The root directory path.
+        recursive: Whether to include subdirectories.
+
+    Returns:
+        A list of file paths.
+    """
     if not recursive:
         return [path for path in glob.glob(str(Path(root)) + "/*")]
     paths = []
@@ -101,8 +151,8 @@ def get_all_files(root, recursive=True):
 
 
 def return_two_vals(
-    vals: tuple[str | None, str | None] | list[str] | str | int | float
-) -> tuple[str | int | float, str | int | float | None]:
+    vals: tuple[str, str] | list[str] | str | int | float
+) -> tuple[str | int | float, str | int | float]:
     """Return a two-length tuple from a str/int/float or list/tuple of length 1 or 2.
 
     Returns 'vals' as a 2-length tuple. If the input is a string, return
@@ -117,7 +167,7 @@ def return_two_vals(
     """
     if isinstance(vals, str):
         return vals, vals
-    if hasattr(vals, "__iter__"):
+    if isinstance(vals, (tuple, list)):
         if len(vals) == 2:
             return vals[0], vals[1]
         if len(vals) == 1:
@@ -156,44 +206,31 @@ def unit_is_degrees(gdf: GeoDataFrame) -> bool:
 def get_object_name(
     var: object, start: int = 2, stop: int = 7, ignore_self: bool = True
 ) -> str | None:
-    """Searches through the local variables down one level at a time."""
-    frame = inspect.currentframe()
-
-    for _ in range(start):
-        frame = frame.f_back
-
-    for _ in np.arange(start, stop):
-        names = [
-            var_name for var_name, var_val in frame.f_locals.items() if var_val is var
-        ]
-        if names and len(names) == 1:
-            if ignore_self and names[0] == "self":
-                frame = frame.f_back
-                continue
-            return names[0]
-
-        names = [name for name in names if not name.startswith("_")]
-
-        if names and len(names) == 1:
-            if ignore_self and names[0] == "self":
-                frame = frame.f_back
-                continue
-
-            return names[0]
-
-        if names and len(names) > 1:
-            if ignore_self and names[0] == "self":
-                frame = frame.f_back
-                continue
-            warnings.warn(
-                "More than one local variable matches the object. Name might be wrong."
-            )
-            return names[0]
-
-        frame = frame.f_back
-
-        if not frame:
-            return
+    frame = inspect.currentframe()  # frame can be FrameType or None
+    if frame:
+        try:
+            for _ in range(start):
+                frame = frame.f_back if frame else None
+            for _ in range(start, stop):
+                if frame:
+                    names = [
+                        var_name
+                        for var_name, var_val in frame.f_locals.items()
+                        if var_val is var and not (ignore_self and var_name == "self")
+                    ]
+                    names = [name for name in names if not name.startswith("_")]
+                    if names:
+                        if len(names) != 1:
+                            warnings.warn(
+                                "More than one local variable matches the object. Name might be wrong.",
+                                stacklevel=2,
+                            )
+                        return names[0]
+                frame = frame.f_back if frame else None
+        finally:
+            if frame:
+                del frame  # Explicitly delete frame reference to assist with garbage collection
+    return None
 
 
 def make_namedict(gdfs: tuple[GeoDataFrame]) -> dict[int, str]:
@@ -207,7 +244,16 @@ def make_namedict(gdfs: tuple[GeoDataFrame]) -> dict[int, str]:
     return namedict
 
 
-def sort_nans_last(df, ignore_index: bool = False):
+def sort_nans_last(df: pd.DataFrame, ignore_index: bool = False) -> pd.DataFrame:
+    """Sort a DataFrame placing rows with the most NaNs last.
+
+    Args:
+        df: DataFrame to sort.
+        ignore_index: If True, the index will be reset.
+
+    Returns:
+        Sorted DataFrame with NaNs last.
+    """
     if not len(df):
         return df
     df["n_nan"] = df.isna().sum(axis=1).values
@@ -219,7 +265,15 @@ def sort_nans_last(df, ignore_index: bool = False):
     return df.reset_index(drop=True) if ignore_index else df
 
 
-def is_number(text) -> bool:
+def is_number(text: str) -> bool:
+    """Check if a string can be converted to a number.
+
+    Args:
+        text: The string to check.
+
+    Returns:
+        True if the string can be converted to a number, False otherwise.
+    """
     try:
         float(text)
         return True
@@ -228,10 +282,14 @@ def is_number(text) -> bool:
 
 
 class LocalFunctionError(ValueError):
-    def __init__(self, func: str):
+    """Exception for when a locally defined function is used in Jupyter, which is incompatible with multiprocessing."""
+
+    def __init__(self, func: Callable) -> None:
+        """Initialiser."""
         self.func = func.__name__
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """Error message representation."""
         return (
             f"{self.func}. "
             "In Jupyter, functions to be parallelized must \n"