API: deprecate legacy API in favour of Graph-based functional impleme…

…ntation (#619)

* API: deprecation notices on legacy api

* fix decorator types

.github/workflows/tests.yaml

@@ -19,6 +19,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  ALLOW_LEGACY_MOMEPY: true
+
 jobs:
   Test:
     name: ${{ matrix.os }}, ${{ matrix.environment-file }}

momepy/dimension.py

@@ -275,7 +275,6 @@ class CourtyardArea:
     """
 
     def __init__(self, gdf, areas=None):
-        # TODO: deprecate in favor of courtyard_area
         self.gdf = gdf
 
         gdf = gdf.copy()
@@ -329,7 +328,7 @@ def __init__(self, gdf):
         self.series = hulls.apply(lambda g: _circle_radius(list(g.coords))) * 2
 
 
-@deprecated("describe")
+@removed("`.describe()` method of libpysal.graph.Graph")
 class AverageCharacter:
     """
     Calculates the average of a character within a set
@@ -476,6 +475,7 @@ def __init__(
             self.mode = pd.Series(modes, index=gdf.index)
 
 
+@deprecated("street_profile")
 class StreetProfile:
     """
     Calculates the street profile characters. This functions
@@ -548,8 +548,6 @@ def __init__(
         distance=10,
         tick_length=50,
     ):
-        # TODO: turn into a function with a variable return like np.unique. Maybe
-        # TODO: check if we can avoid some of the loops
         self.left = left
         self.right = right
         self.distance = distance
@@ -706,6 +704,7 @@ def _get_point2(self, pt, bearing, dist):
         return (x, y)
 
 
+@deprecated("weighted_character")
 class WeightedCharacter:
     """
     Calculates the weighted character. Character weighted by the area
@@ -765,9 +764,6 @@ class WeightedCharacter:
     def __init__(
         self, gdf, values, spatial_weights, unique_id, areas=None, verbose=True
     ):
-        # TODO: Refactoring project note: This is a lag using a graph where weight
-        # TODO: represents row-normalied area. It now includes self but that shall be
-        # TODO: optional.
         self.gdf = gdf
         self.sw = spatial_weights
         self.id = gdf[unique_id]
@@ -804,6 +800,7 @@ def __init__(
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@removed("`.describe()` method of libpysal.graph.Graph")
 class CoveredArea:
     """
     Calculates the area covered by neighbours, which is total area covered
@@ -840,9 +837,6 @@ class CoveredArea:
     """
 
     def __init__(self, gdf, spatial_weights, unique_id, verbose=True):
-        # TODO: Refactoring project note: This is just a lag with binary weights over
-        # TODO: the area using the graph with self-weights. Maybe point to that?
-
         self.gdf = gdf
         self.sw = spatial_weights
         self.id = gdf[unique_id]
@@ -944,6 +938,7 @@ def __init__(self, gdf, spatial_weights=None, verbose=True):
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@removed("`.describe()` or `.lag()` methods of libpysal.graph.Graph")
 class SegmentsLength:
     """
     Calculate the cummulative and/or mean length of segments. Length of segments
@@ -989,10 +984,6 @@ class SegmentsLength:
     """
 
     def __init__(self, gdf, spatial_weights=None, mean=False, verbose=True):
-        # TODO: Refactoring project note: This is just a lag with binary (sum) or
-        # TODO: row-standardized graph that includes self weight over lenghts.
-        # TODO: Worth wrapping or point to lag? Probably latter?
-
         self.gdf = gdf
 
         if spatial_weights is None:

momepy/distribution.py

@@ -2,8 +2,9 @@
 
 # distribution.py
 # definitions of spatial distribution characters
-
 import math
+import os
+import warnings
 
 import geopandas as gpd
 import networkx as nx
@@ -13,7 +14,7 @@
 from packaging.version import Version
 from tqdm.auto import tqdm  # progress bar
 
-from .utils import _azimuth
+from .utils import _azimuth, deprecated
 
 __all__ = [
     "Orientation",
@@ -32,6 +33,7 @@
 GPD_GE_013 = Version(gpd.__version__) >= Version("0.13.0")
 
 
+@deprecated("orientation")
 class Orientation:
     """
     Calculate the orientation of object. The deviation of orientation from cardinal
@@ -136,6 +138,21 @@ class SharedWalls:
     """
 
     def __init__(self, gdf):
+        if os.getenv("ALLOW_LEGACY_MOMEPY", "False").lower() not in (
+            "true",
+            "1",
+            "yes",
+        ):
+            warnings.warn(
+                "Class based API like `momepy.SharedWalls` or `momepy.SharedWallsRatio`"
+                " is deprecated. Replace it with `momepy.shared_walls` or explicitly "
+                "computing `momepy.shared_walls / gdf.length` respectively to use "
+                "functional API instead or pin momepy version <1.0. Class-based API "
+                "will be removed in 1.0. ",
+                # "See details at https://docs.momepy.org/en/stable/migration.html",
+                FutureWarning,
+                stacklevel=2,
+            )
         self.gdf = gdf
 
         if GPD_GE_013:
@@ -206,6 +223,7 @@ def __init__(self, gdf, perimeters=None):
         self.series = self.series / self.perimeters
 
 
+@deprecated("street_alignment")
 class StreetAlignment:
     """
     Calculate the difference between street orientation and orientation of
@@ -321,6 +339,7 @@ def __init__(
         self.series.index = left.index
 
 
+@deprecated("cell_alignment")
 class CellAlignment:
     """
     Calculate the difference between cell orientation and the orientation of object.
@@ -417,6 +436,7 @@ def __init__(
         self.series.index = left.index
 
 
+@deprecated("alignment")
 class Alignment:
     """
     Calculate the mean deviation of solar orientation of objects on adjacent cells
@@ -496,6 +516,7 @@ def __init__(self, gdf, spatial_weights, unique_id, orientations, verbose=True):
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("neighbor_distance")
 class NeighborDistance:
     """
     Calculate the mean distance to adjacent buildings (based on ``spatial_weights``).
@@ -564,6 +585,7 @@ def __init__(self, gdf, spatial_weights, unique_id, verbose=True):
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("mean_interbuilding_distance")
 class MeanInterbuildingDistance:
     """
     Calculate the mean interbuilding distance. Interbuilding distances are
@@ -736,6 +758,7 @@ def _orient(self, geom):
         return az
 
 
+@deprecated("building_adjacency")
 class BuildingAdjacency:
     """
     Calculate the level of building adjacency. Building adjacency reflects how much
@@ -831,6 +854,7 @@ def __init__(
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("neighbors")
 class Neighbors:
     """
     Calculate the number of neighbours captured by ``spatial_weights``. If

momepy/diversity.py

@@ -11,6 +11,8 @@
 from numpy.lib import NumpyVersion
 from tqdm.auto import tqdm  # progress bar
 
+from .utils import deprecated, removed
+
 __all__ = [
     "Range",
     "Theil",
@@ -24,6 +26,7 @@
 ]
 
 
+@deprecated("values_range")
 class Range:
     """
     Calculates the range of values within neighbours defined in ``spatial_weights``.
@@ -119,6 +122,7 @@ def __init__(
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("theil")
 class Theil:
     """
     Calculates the Theil measure of inequality of values within neighbours defined in
@@ -217,6 +221,7 @@ def __init__(self, gdf, values, spatial_weights, unique_id, rng=None, verbose=Tr
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("simpson")
 class Simpson:
     """
     Calculates the Simpson's diversity index of values within neighbours defined in
@@ -402,6 +407,7 @@ def simpson_diversity(values, bins=None, categorical=False):
     return sum((n / sum(counts)) ** 2 for n in counts if n != 0)
 
 
+@deprecated("gini")
 class Gini:
     """
     Calculates the Gini index of values within neighbours defined in
@@ -503,6 +509,7 @@ def __init__(self, gdf, values, spatial_weights, unique_id, rng=None, verbose=Tr
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("shannon")
 class Shannon:
     """
     Calculates the Shannon index of values within neighbours defined in
@@ -690,6 +697,7 @@ def p(n, sum_n):
     return -sum(p(n, sum(counts.values())) for n in counts.values() if n != 0)
 
 
+@removed("`.describe()` method of libpysal.graph.Graph")
 class Unique:
     """
     Calculates the number of unique values within neighbours defined in
@@ -766,6 +774,7 @@ def __init__(
         self.series = pd.Series(results_list, index=gdf.index)
 
 
+@deprecated("percentile")
 class Percentiles:
     """
     Calculates the percentiles of values within

momepy/elements.py

@@ -2,6 +2,7 @@
 
 # elements.py
 # generating derived elements (street edge, block)
+import os
 import warnings
 
 import geopandas as gpd
@@ -15,6 +16,8 @@
 from shapely.ops import polygonize
 from tqdm.auto import tqdm
 
+from .utils import deprecated
+
 __all__ = [
     "Tessellation",
     "Blocks",
@@ -170,6 +173,22 @@ def __init__(
         use_dask=True,
         n_chunks=None,
     ):
+        if os.getenv("ALLOW_LEGACY_MOMEPY", "False").lower() not in (
+            "true",
+            "1",
+            "yes",
+        ):
+            warnings.warn(
+                "Class based API like `momepy.Tessellation` is deprecated. "
+                "Replace it with `momepy.morphological_tessellation` or "
+                "`momepy.enclosed_tessellation` to use functional API instead "
+                "or pin momepy version <1.0. Class-based API will be removed in "
+                "1.0. "
+                # "See details at https://docs.momepy.org/en/stable/migration.html",
+                "",
+                FutureWarning,
+                stacklevel=2,
+            )
         self.gdf = gdf
         self.id = gdf[unique_id]
         self.limit = limit
@@ -527,6 +546,7 @@ def _tess(
         )
 
 
+@deprecated("generate_blocks")
 class Blocks:
     """
     Generate blocks based on buildings, tessellation, and street network.
@@ -633,6 +653,7 @@ def __init__(self, tessellation, edges, buildings, id_name, unique_id):
         self.blocks = blocks
 
 
+@deprecated("get_nearest_street")
 def get_network_id(left, right, network_id, min_size=100, verbose=True):
     """
     Snap each element (preferably building) to the closest
@@ -724,6 +745,7 @@ def get_network_id(left, right, network_id, min_size=100, verbose=True):
     return series
 
 
+@deprecated("get_nearest_node")
 def get_node_id(
     objects,
     nodes,