docstring & typehints in simplify.simplify_singletons(), etc.

sgeop/simplify.py

@@ -29,31 +29,66 @@
 
 
 def simplify_singletons(
-    artifacts,
-    roads,
-    max_segment_length=1,
-    compute_coins=True,
-    min_dangle_length=10,
-    eps=1e-4,
-    clip_limit: int = 2,
-    simplification_factor=2,
-    consolidation_tolerance=10,
-):
-    """
+    artifacts: gpd.GeoDataFrame,
+    roads: gpd.GeoDataFrame,
+    max_segment_length: float | int = 1,
+    compute_coins: bool = True,
+    min_dangle_length: float | int = 10,
+    eps: float = 1e-4,
+    clip_limit: float | int = 2,
+    simplification_factor: float | int = 2,
+    consolidation_tolerance: float | int = 10,
+) -> gpd.GeoDataFrame:
+    """Simplification of singleton face artifacts – the first simplification step in
+    the procedure detailed in ``simplify.simplify_loop()``.
+
+    This process extracts nodes from network edges before computing and labeling
+    face artifacts with a ``{C, E, S}`` typology through ``momepy.COINS`` via the
+    constituent road geometries.
+
+    Next, the artifacts' constituent line geometries are either dropped or added in
+    the following order of typologies:
+        1. 1 node and 1 continuity group
+        2. more than 1 node and 1 or more identical continuity groups
+        3. 2 or more nodes and 2 or more continuity groups
+
+    Non-planar geometries are ignored.
 
     Parameters
     ----------
-
-    clip_limit : int = 2
-        Following generation of the Voronoi linework in ``geometry.voronoi_skeleton()``,
-        we clip to fit inside the polygon. To ensure we get a space to make proper
-        topological connections from the linework to the actual points on the edge of
-        the polygon, we clip using a polygon with a negative buffer of ``clip_limit``
-        or the radius of maximum inscribed circle, whichever is smaller.
+    artifacts : geopandas.GeoDataFrame
+        Face artifact polygons.
+    roads : geopandas.GeoDataFrame
+        Preprocessed road network data.
+    max_segment_length : float | int = 1
+        Additional vertices will be added so that all line segments
+        are no longer than this value. Must be greater than 0.
+        Used in multiple internal geometric operations.
+    compute_coins : bool = True
+        Flag for computing and labeling artifacts with a ``{C, E, S}`` typology through
+        ``momepy.COINS`` via the constituent road geometries.
+    min_dangle_length : float | int = 10
+        The threshold for determining if linestrings are dangling slivers to be
+        removed or not.
+    eps : float = 1e-4
+        Tolerance epsilon used in multiple internal geometric operations.
+    clip_limit : float | int = 2
+        Following generation of the Voronoi linework, we clip to fit inside the
+        polygon. To ensure we get a space to make proper topological connections
+        from the linework to the actual points on the edge of the polygon, we clip
+        using a polygon with a negative buffer of ``clip_limit`` or the radius of
+        maximum inscribed circle, whichever is smaller.
+    simplification_factor : float | int = 2
+        The factor by which singles, pairs, and clusters are simplified. The
+        ``max_segment_length`` is multiplied by this factor to get the
+        simplification epsilon.
+    consolidation_tolerance : float | int = 10
+        Tolerance passed to node consolidation when generating Voronoi skeletons.
 
     Returns
     -------
-
+    geopandas.GeoDataFrame
+        The road network line data following singletons.
     """
 
     # Get nodes from the network.
@@ -650,7 +685,7 @@ def simplify_loop(
         Additional vertices will be added so that all line segments
         are no longer than this value. Must be greater than 0.
         Used in multiple internal geometric operations.
-    min_dangle_length : float | int
+    min_dangle_length : float | int = 20
         The threshold for determining if linestrings are dangling slivers to be
         removed or not.
     clip_limit : float | int = 2