Functional arearatio

momepy/functional/_intensity.py

@@ -5,7 +5,9 @@
 from libpysal.graph import Graph
 from pandas import Series
 
-__all__ = ["courtyards", "node_density"]
+from momepy import describe_reached
+
+__all__ = ["courtyards", "node_density", "area_ratio"]
 
 
 def courtyards(geometry: GeoDataFrame | GeoSeries, graph: Graph) -> Series:
@@ -111,3 +113,40 @@ def _calc_nodedensity(group, edges):
         summation_values = pd.Series(np.ones(nodes.shape[0]), index=nodes.index)
 
     return graph.apply(summation_values, _calc_nodedensity, edges=edges)
+
+
+def area_ratio(
+    left: Series, right: Series, right_group_key: Series | np.ndarray
+) -> pd.Series:
+    """Calculate covered area ratio or floor area ratio of objects.
+    .. math::
+        \\textit{covering object area} \\over \\textit{covered object area}
+
+    Adapted from :cite:`schirmer2015`.
+
+    Parameters
+    ----------
+    left : Series
+        A GeoDataFrame with the areas of the objects being covered (e.g. land unit).
+    right : Series
+        A GeoDataFrame with the areas of the covering objects (e.g. building).
+    right_group_key: np.array | pd.Series
+        The group key that assigns objects from ``right`` to ``left``.
+
+    Returns
+    -------
+    Series
+
+
+    Examples
+    --------
+    >>> tessellation_df['CAR'] = mm.area_ratio(tessellation_df['area'],
+    ...                                       buildings_df['area'],
+    ...                                       buildings_df['uID'])
+    """
+
+    # if isinstance(right_group_key, np.ndarray):
+    #     right_group_key = pd.Series(right_group_key, index=right.index)
+
+    results = describe_reached(right, right_group_key, result_index=left.index)
+    return results["sum"] / left.values

momepy/functional/tests/test_intensity.py

@@ -90,6 +90,66 @@ def test_node_density(self):
         ):
             mm.node_density(edges, edges, g, weighted=True)
 
+    def test_area_ratio(self):
+        car_block = mm.area_ratio(
+            self.blocks.geometry.area,
+            self.df_buildings["area"],
+            self.df_buildings["bID"],
+        )
+        car_block_expected = {
+            "mean": 0.27619743196980123,
+            "max": 0.35699143584461146,
+            "min": 0.12975039475826336,
+            "count": 8,
+        }
+
+        assert_result(car_block, car_block_expected, self.blocks)
+
+        car = mm.area_ratio(
+            self.df_tessellation.geometry.area,
+            self.df_buildings["area"],
+            self.df_buildings["uID"] - 1,
+        )
+        car2 = mm.area_ratio(
+            self.df_tessellation.set_index("uID").area,
+            self.df_buildings.set_index("uID").area,
+            self.df_tessellation.set_index("uID").index,
+        )
+        car_expected = {
+            "mean": 0.3206556897709747,
+            "max": 0.8754071653707558,
+            "min": 0.029097983413141276,
+            "count": 144,
+        }
+        assert_result(car, car_expected, self.df_tessellation)
+        assert_result(car2, car_expected, self.df_tessellation.set_index("uID"))
+
+        car_sel = mm.area_ratio(
+            self.df_tessellation.iloc[10:20]["area"],
+            self.df_buildings["area"],
+            self.df_tessellation.iloc[10:20]["uID"] - 1,
+        )
+        car_sel_expected = {
+            "mean": 0.3892868062654601,
+            "max": 0.5428192449477212,
+            "min": 0.22057633949526625,
+            "count": 10,
+        }
+        assert_result(car_sel, car_sel_expected, self.df_tessellation.iloc[10:20])
+
+        far = mm.area_ratio(
+            self.df_tessellation.geometry.area,
+            self.df_buildings["fl_area"],
+            self.df_buildings["uID"] - 1,
+        )
+        far_expected = {
+            "mean": 1.910949846262234,
+            "max": 7.003257322966046,
+            "min": 0.26188185071827147,
+            "count": 144,
+        }
+        assert_result(far, far_expected, self.df_tessellation)
+
 
 class TestIntensityEquality:
     def setup_method(self):
@@ -123,6 +183,69 @@ def test_courtyards(self):
             new_courtyards, old_courtyards, check_names=False, check_dtype=False
         )
 
+    def test_area_ratio(self):
+        self.blocks["area"] = self.blocks.geometry.area
+        car_block_new = mm.area_ratio(
+            self.blocks.geometry.area,
+            self.df_buildings["area"],
+            self.df_buildings["bID"],
+        )
+        car_block_old = mm.AreaRatio(
+            self.blocks, self.df_buildings, "area", "area", "bID"
+        ).series
+        assert_series_equal(
+            car_block_new, car_block_old, check_dtype=False, check_names=False
+        )
+
+        car_new = mm.area_ratio(
+            self.df_tessellation.geometry.area,
+            self.df_buildings["area"],
+            self.df_buildings["uID"] - 1,
+        )
+        car2_new = mm.area_ratio(
+            self.df_tessellation.set_index("uID").area,
+            self.df_buildings.set_index("uID").area,
+            self.df_tessellation.set_index("uID").index,
+        )
+        car_old = mm.AreaRatio(
+            self.df_tessellation, self.df_buildings, "area", "area", "uID"
+        ).series
+        assert_series_equal(car_new, car_old, check_dtype=False, check_names=False)
+        assert_series_equal(
+            car_old,
+            car2_new.reset_index(drop=True),
+            check_dtype=False,
+            check_names=False,
+            check_index_type=False,
+        )
+
+        car_sel = mm.AreaRatio(
+            self.df_tessellation.iloc[10:20], self.df_buildings, "area", "area", "uID"
+        ).series
+        car_sel_new = mm.area_ratio(
+            self.df_tessellation.iloc[10:20]["area"],
+            self.df_buildings["area"],
+            self.df_tessellation.iloc[10:20]["uID"] - 1,
+        )
+
+        assert_series_equal(car_sel_new, car_sel, check_dtype=False, check_names=False)
+
+        far_new = mm.area_ratio(
+            self.df_tessellation.geometry.area,
+            self.df_buildings["fl_area"],
+            self.df_buildings["uID"] - 1,
+        )
+
+        far_old = mm.AreaRatio(
+            self.df_tessellation,
+            self.df_buildings,
+            self.df_tessellation.area,
+            self.df_buildings.fl_area,
+            "uID",
+        ).series
+
+        assert_series_equal(far_new, far_old, check_dtype=False, check_names=False)
+
     def test_node_density(self):
         nx = mm.gdf_to_nx(self.df_streets, integer_labels=True)
         nx = mm.node_degree(nx)