ObjectNat 1.2.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

objectnat/methods/provision/provision.py

@@ -1,5 +1,3 @@
-from typing import Tuple
-
 import geopandas as gpd
 import numpy as np
 import pandas as pd
@@ -18,29 +16,53 @@ def get_service_provision(
     threshold: int,
     buildings_demand_column: str = "demand",
     services_capacity_column: str = "capacity",
-    pandarallel_init_kwargs: dict = None,
-) -> Tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
-    """Calculate load from buildings with demands on the given services using the distances matrix between them.
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+    """
+    Compute service provision between demand locations (buildings) and service facilities.
 
-    Parameters:
-        services (gpd.GeoDataFrame):
-            GeoDataFrame of services
-        adjacency_matrix (pd.DataFrame):
-            DataFrame representing the adjacency matrix
+    The function implements a **gravity-based allocation model**: service capacity is
+    distributed across nearby demand points with weights that **decay with the square
+    of distance (or generalized cost)**. Closer buildings receive proportionally
+    higher shares of the available capacity.
+
+    Args:
         buildings (gpd.GeoDataFrame):
-            GeoDataFrame of demanded buildings
+            GeoDataFrame of **demand locations** (e.g., residential buildings).
+            Must include a numeric column with demand values
+            (see ``buildings_demand_column``).
+        adjacency_matrix (pd.DataFrame):
+            A rectangular DataFrame representing **OD (origin–destination) costs**
+            between ``buildings`` (rows) and ``services`` (columns).
+            Units must match ``threshold`` (e.g., minutes or meters).
+            Missing or infinite values (``NaN`` or ``inf``) are treated as **unreachable**.
+            The row index must match ``buildings.index`` and column index must
+            match ``services.index``.
+        services (gpd.GeoDataFrame):
+            GeoDataFrame of **service facilities** (e.g., schools, clinics).
+            Must include a numeric column with service capacity
+            (see ``services_capacity_column``).
         threshold (int):
-            Threshold value
+            Maximum allowed cost value for assignment.
+            Any OD entry **greater than this threshold** is considered unreachable.
+            Units are the same as in ``adjacency_matrix``.
         buildings_demand_column (str):
-            column name of buildings demands
+            Column name of building demand values. Default is ``"demand"``.
         services_capacity_column (str):
-            column name of services capacity
-        pandarallel_init_kwargs (dict):
-            Dictionary of keyword arguments to pass to pandarallel
+            Column name of service capacity values. Default is ``"capacity"``.
 
     Returns:
-        (Tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]): Tuple of GeoDataFrames representing provision
-        buildings, provision services, and provision links
+        Tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+            A tuple of three GeoDataFrames:
+
+            - **buildings**: input buildings with updated provision metrics.
+            - **services**: input services with updated load and capacity metrics.
+            - **links**: building–service links within the threshold, containing
+              allocated demand shares and distances/costs based on the gravity model.
+
+    Notes:
+        - The model is **gravity-based**, with cost weights decaying by the **square of distance**.
+        - Unreachable OD pairs (``NaN`` or ``inf``) are ignored.
+        - The function does not perform routing; it expects a precomputed OD matrix.
     """
     buildings = buildings.copy()
     services = services.copy()
@@ -53,15 +75,42 @@ def get_service_provision(
         demanded_buildings=buildings,
         adjacency_matrix=adjacency_matrix,
         threshold=threshold,
-        pandarallel_init_kwargs=pandarallel_init_kwargs,
     ).run()
     return provision_buildings, provision_services, provision_links
 
 
 def clip_provision(
     buildings: gpd.GeoDataFrame, services: gpd.GeoDataFrame, links: gpd.GeoDataFrame, selection_zone: gpd.GeoDataFrame
-) -> Tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+    """
+    Clip service provision results to a specific geographic boundary.
+
+    Keeps only:
+      * buildings that intersect the ``selection_zone``;
+      * links that connect to the kept buildings;
+      * services referenced by those links.
+
+    Args:
+        buildings:
+            GeoDataFrame of buildings **after** :func:`get_service_provision`.
+        services:
+            GeoDataFrame of services **after** :func:`get_service_provision`.
+        links:
+            GeoDataFrame of building–service links from
+            :func:`get_service_provision`. Must include indices or columns
+            to match buildings and services.
+        selection_zone:
+            GeoDataFrame (polygon or multipolygon) defining the clipping area.
+
+    Returns:
+        Tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+            The filtered subsets of buildings, services, and links
+            that fall inside the specified zone.
 
+    Notes:
+        - The function performs **spatial filtering only**.
+          It does **not** recompute or redistribute demand/supply.
+    """
     assert selection_zone.crs == buildings.crs == services.crs == links.crs, (
         f"CRS mismatch: buildings_crs:{buildings.crs}, "
         f"links_crs:{links.crs} , "
@@ -83,6 +132,49 @@ def clip_provision(
 def recalculate_links(
     buildings: gpd.GeoDataFrame, services: gpd.GeoDataFrame, links: gpd.GeoDataFrame, new_max_dist: float
 ) -> tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+    """
+    Recalculate provision aggregates after tightening the accessibility threshold.
+
+    Removes all links whose cost (distance or time) exceeds ``new_max_dist``, then
+    updates demand and capacity aggregates accordingly. This is done **without
+    redistributing** removed demand to alternative services.
+
+    Args:
+        buildings:
+            GeoDataFrame of buildings after :func:`get_service_provision`.
+            Expected to include provision-related fields such as demand, demand_left,
+            supplied demand, and average distance/cost.
+
+        services:
+            GeoDataFrame of services after :func:`get_service_provision`, with
+            fields describing remaining capacity and service load.
+
+        links:
+            GeoDataFrame of building–service links containing at least:
+
+            - ``building_index``
+            - ``service_index``
+            - ``distance`` (or time cost, in the same units as ``new_max_dist``)
+            - ``demand`` (assigned portion)
+
+        new_max_dist:
+            New maximum allowed cost value (same units as OD/threshold).
+            Links with cost **greater than** this value are removed.
+
+    Returns:
+        tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, gpd.GeoDataFrame]:
+            - **buildings**: updated aggregate demand metrics and recalculated
+              average cost.
+            - **services**: updated load and capacity fields after freeing excess capacity.
+            - **links**: subset of links that remain within the new threshold.
+
+    Notes:
+        - If no links exceed ``new_max_dist``, the function logs a warning
+          and returns the original inputs unchanged.
+        - Average cost values are recomputed based on remaining links.
+          If a building has no remaining assigned demand, ``avg_dist`` becomes ``NaN``.
+        - Removed demand is **not reallocated** to other services.
+    """
     buildings = buildings.copy()
     services = services.copy()
     links = links.copy()

objectnat/methods/provision/provision_exceptions.py

@@ -1,59 +1,59 @@
-class CapacityKeyError(KeyError):
-    def __init__(self, *args):
-        if args:
-            self.message = args[0]
-        else:
-            self.message = None
-
-    def __str__(self):
-        if self.message:
-            return f"CapacityKeyError, {self.message} "
-
-        return (
-            "Column 'capacity' was not found in provided 'services' GeoDataFrame. This attribute "
-            "corresponds to the total capacity for each service."
-        )
-
-
-class CapacityValueError(ValueError):
-    def __init__(self, *args):
-        if args:
-            self.message = args[0]
-        else:
-            self.message = None
-
-    def __str__(self):
-        if self.message:
-            return f"CapacityValueError, {self.message} "
-
-        return "Column 'capacity' in 'services' GeoDataFrame  has no valid value."
-
-
-class DemandKeyError(KeyError):
-    def __init__(self, *args):
-        if args:
-            self.message = args[0]
-        else:
-            self.message = None
-
-    def __str__(self):
-        if self.message:
-            return f"DemandKeyError, {self.message} "
-
-        return (
-            "The column 'demand' was not found in the provided 'demanded_buildings' GeoDataFrame. "
-            "This attribute corresponds to the number of demands for the selected service in each building."
-        )
-
-
-class DemandValueError(ValueError):
-    def __init__(self, *args):
-        if args:
-            self.message = args[0]
-        else:
-            self.message = None
-
-    def __str__(self):
-        if self.message:
-            return f"DemandValueError, {self.message} "
-        return "Column 'demand' in 'demanded_buildings' GeoDataFrame  has no valid value."
+class CapacityKeyError(KeyError):
+    def __init__(self, *args):
+        if args:
+            self.message = args[0]
+        else:
+            self.message = None
+
+    def __str__(self):
+        if self.message:
+            return f"CapacityKeyError, {self.message} "
+
+        return (
+            "Column 'capacity' was not found in provided 'services' GeoDataFrame. This attribute "
+            "corresponds to the total capacity for each service."
+        )
+
+
+class CapacityValueError(ValueError):
+    def __init__(self, *args):
+        if args:
+            self.message = args[0]
+        else:
+            self.message = None
+
+    def __str__(self):
+        if self.message:
+            return f"CapacityValueError, {self.message} "
+
+        return "Column 'capacity' in 'services' GeoDataFrame  has no valid value."
+
+
+class DemandKeyError(KeyError):
+    def __init__(self, *args):
+        if args:
+            self.message = args[0]
+        else:
+            self.message = None
+
+    def __str__(self):
+        if self.message:
+            return f"DemandKeyError, {self.message} "
+
+        return (
+            "The column 'demand' was not found in the provided 'demanded_buildings' GeoDataFrame. "
+            "This attribute corresponds to the number of demands for the selected service in each building."
+        )
+
+
+class DemandValueError(ValueError):
+    def __init__(self, *args):
+        if args:
+            self.message = args[0]
+        else:
+            self.message = None
+
+    def __str__(self):
+        if self.message:
+            return f"DemandValueError, {self.message} "
+        return "Column 'demand' in 'demanded_buildings' GeoDataFrame  has no valid value."