huff 1.2.0__py3-none-any.whl → 1.3.1__py3-none-any.whl

huff/gistools.py

@@ -4,13 +4,15 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.2.0
-# Last update: 2025-05-14 18:28
+# Version:     1.3.1
+# Last update: 2025-05-28 18:01
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
 
 import geopandas as gp
+import pandas as pd
+from pandas.api.types import is_numeric_dtype
 from math import pi, sin, cos, acos
 
 
@@ -60,6 +62,65 @@ def distance_matrix(
     return matrix
 
 
+def buffers(
+    point_gdf: gp.GeoDataFrame,
+    unique_id_col: str,
+    distances: list,
+    donut: bool = True,
+    save_output: bool = True,
+    output_filepath: str = "buffers.shp",
+    output_crs: str = "EPSG:4326"
+    ):    
+  
+    all_buffers_gdf = gp.GeoDataFrame(columns=[unique_id_col, "segment", "geometry"])
+
+    for idx, row in point_gdf.iterrows():
+
+        point_buffers = []
+
+        for distance in distances:
+
+            point = row["geometry"] 
+            point_buffer = point.buffer(distance)
+
+            point_buffer_gdf = gp.GeoDataFrame(
+            {
+                unique_id_col: row[unique_id_col],
+                "geometry": [point_buffer], 
+                "segment": [distance]
+                },
+                crs=point_gdf.crs
+            )
+        
+            point_buffers.append(point_buffer_gdf)
+
+        point_buffers_gdf = pd.concat(
+            point_buffers, 
+            ignore_index = True
+            )
+
+        if donut:
+            point_buffers_gdf = overlay_difference(
+                polygon_gdf = point_buffers_gdf, 
+                sort_col = "segment"
+                )
+ 
+        all_buffers_gdf = pd.concat(
+            [
+                all_buffers_gdf,
+                point_buffers_gdf
+                ], 
+            ignore_index = True)
+
+    all_buffers_gdf = all_buffers_gdf.to_crs(output_crs)
+
+    if save_output:
+        all_buffers_gdf.to_file(output_filepath)
+        print ("Saved as", output_filepath)
+
+    return all_buffers_gdf 
+
+
 def overlay_difference(
     polygon_gdf: gp.GeoDataFrame, 
     sort_col: str = None,
@@ -74,6 +135,7 @@ def overlay_difference(
     new_data = []
 
     for i in range(len(polygon_gdf) - 1, 0, -1):
+        
         current_polygon = polygon_gdf.iloc[i].geometry
         previous_polygon = polygon_gdf.iloc[i - 1].geometry
         difference_polygon = current_polygon.difference(previous_polygon)
@@ -85,7 +147,9 @@ def overlay_difference(
         new_data.append(polygon_gdf.iloc[i].drop("geometry"))
 
     inner_most_polygon = polygon_gdf.iloc[0].geometry
+
     if inner_most_polygon.is_valid:
+
         new_geometries.append(inner_most_polygon)
         new_data.append(polygon_gdf.iloc[0].drop("geometry"))
 
@@ -93,4 +157,60 @@ def overlay_difference(
         new_data, geometry=new_geometries, crs=polygon_gdf.crs
     )
 
-    return polygon_gdf_difference
+    return polygon_gdf_difference
+
+
+def point_spatial_join(
+    polygon_gdf: gp.GeoDataFrame,
+    point_gdf: gp.GeoDataFrame,
+    join_type: str = "inner",
+    polygon_ref_cols: list = [],
+    point_stat_col: str = None
+    ):
+    
+    if polygon_gdf.crs != point_gdf.crs:
+        raise ValueError (f"Coordinate reference systems of polygon and point data do not match. Polygons: {str(polygon_gdf.crs)}, points: {str(point_gdf.crs)}")
+    
+    if polygon_ref_cols != []:
+        for polygon_ref_col in polygon_ref_cols:
+            if polygon_ref_col not in polygon_gdf.columns:
+                raise KeyError (f"Column {polygon_ref_col} not in polygon data")
+        
+    if point_stat_col is not None:
+        if point_stat_col not in point_gdf.columns:
+            raise KeyError (f"Column {point_stat_col} not in point data")
+        if not is_numeric_dtype(point_gdf[point_stat_col]):
+            raise TypeError (f"Column {point_stat_col} is not numeric")
+               
+    shp_points_gdf_join = point_gdf.sjoin(
+        polygon_gdf, 
+        how=join_type
+        )
+
+    spatial_join_stat = None
+
+    if polygon_ref_cols != [] and point_stat_col is not None:
+        shp_points_gdf_join_count = shp_points_gdf_join.groupby(polygon_ref_cols)[point_stat_col].count()
+        shp_points_gdf_join_sum = shp_points_gdf_join.groupby(polygon_ref_cols)[point_stat_col].sum()
+        shp_points_gdf_join_min = shp_points_gdf_join.groupby(polygon_ref_cols)[point_stat_col].min()
+        shp_points_gdf_join_max = shp_points_gdf_join.groupby(polygon_ref_cols)[point_stat_col].max()
+        shp_points_gdf_join_mean = shp_points_gdf_join.groupby(polygon_ref_cols)[point_stat_col].mean()
+        
+        shp_points_gdf_join_count = shp_points_gdf_join_count.rename("count").to_frame()
+        shp_points_gdf_join_sum = shp_points_gdf_join_sum.rename("sum").to_frame()
+        shp_points_gdf_join_min = shp_points_gdf_join_min.rename("min").to_frame()
+        shp_points_gdf_join_max = shp_points_gdf_join_max.rename("max").to_frame()
+        shp_points_gdf_join_mean = shp_points_gdf_join_mean.rename("mean").to_frame()
+        spatial_join_stat = shp_points_gdf_join_count.join(
+            [
+                shp_points_gdf_join_sum, 
+                shp_points_gdf_join_min, 
+                shp_points_gdf_join_max,
+                shp_points_gdf_join_mean
+                ]
+            )
+
+    return [
+        shp_points_gdf_join,
+        spatial_join_stat
+        ]

huff/models.py

@@ -4,8 +4,8 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.2.0
-# Last update: 2025-05-14 18:33
+# Version:     1.3.1
+# Last update: 2025-05-28 18:01
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
@@ -18,7 +18,7 @@ from statsmodels.formula.api import ols
 from shapely.geometry import Point
 from shapely import wkt
 from huff.ors import Client, TimeDistanceMatrix, Isochrone
-from huff.gistools import overlay_difference, distance_matrix
+from huff.gistools import overlay_difference, distance_matrix, buffers
 
 
 class CustomerOrigins:
@@ -28,13 +28,15 @@ class CustomerOrigins:
         geodata_gpd, 
         geodata_gpd_original, 
         metadata,
-        isochrones_gdf
+        isochrones_gdf,
+        buffers_gdf
         ):
 
         self.geodata_gpd = geodata_gpd
         self.geodata_gpd_original = geodata_gpd_original
         self.metadata = metadata
         self.isochrones_gdf = isochrones_gdf
+        self.buffers_gdf = buffers_gdf
 
     def get_geodata_gpd(self):
 
@@ -48,10 +50,14 @@ class CustomerOrigins:
         
         return self.metadata
     
-    def get_isochrones(self):
+    def get_isochrones_gdf(self):
 
         return self.isochrones_gdf
 
+    def get_buffers_gdf(self):
+
+        return self.buffers_gdf
+
     def summary(self):
 
         metadata = self.metadata
@@ -77,6 +83,11 @@ class CustomerOrigins:
         else:
             print("Including isochrones       YES")
 
+        if self.buffers_gdf is None:
+            print("Including buffers          NO")
+        else:
+            print("Including buffers          YES")
+
         return metadata
     
     def define_marketsize(
@@ -151,6 +162,32 @@ class CustomerOrigins:
 
         return self
 
+    def buffers(
+        self,
+        segments_distance: list = [500, 1000],
+        donut: bool = True,
+        save_output: bool = True,
+        output_filepath: str = "customer_origins_buffers.shp",
+        output_crs: str = "EPSG:4326"
+        ):
+
+        geodata_gpd_original = self.get_geodata_gpd_original()
+        metadata = self.metadata
+
+        buffers_gdf = buffers(
+            point_gdf = geodata_gpd_original,
+            unique_id_col = metadata["unique_id"],
+            distances = segments_distance,
+            donut = donut,
+            save_output = save_output,
+            output_filepath = output_filepath,
+            output_crs = output_crs
+            )
+        
+        self.buffers_gdf = buffers_gdf
+
+        return self
+
 
 class SupplyLocations:
 
@@ -159,13 +196,15 @@ class SupplyLocations:
         geodata_gpd, 
         geodata_gpd_original, 
         metadata,
-        isochrones_gdf
+        isochrones_gdf,
+        buffers_gdf
         ):
 
         self.geodata_gpd = geodata_gpd
         self.geodata_gpd_original = geodata_gpd_original
         self.metadata = metadata
         self.isochrones_gdf = isochrones_gdf
+        self.buffers_gdf = buffers_gdf
 
     def get_geodata_gpd(self):
 
@@ -182,6 +221,10 @@ class SupplyLocations:
     def get_isochrones_gdf(self):
 
         return self.isochrones_gdf
+    
+    def get_buffers_gdf(self):
+
+        return self.buffers_gdf
 
     def summary(self):
 
@@ -346,6 +389,32 @@ class SupplyLocations:
 
         return self
 
+    def buffers(
+        self,
+        segments_distance: list = [500, 1000],
+        donut: bool = True,
+        save_output: bool = True,
+        output_filepath: str = "supply_locations_buffers.shp",
+        output_crs: str = "EPSG:4326"
+        ):
+
+        geodata_gpd_original = self.get_geodata_gpd_original()
+        metadata = self.metadata
+
+        buffers_gdf = buffers(
+            point_gdf = geodata_gpd_original,
+            unique_id_col = metadata["unique_id"],
+            distances = segments_distance,
+            donut = donut,
+            save_output = save_output,
+            output_filepath = output_filepath,
+            output_crs = output_crs
+            )
+        
+        self.buffers_gdf = buffers_gdf
+
+        return self
+    
 
 class InteractionMatrix:
 
@@ -459,14 +528,10 @@ class InteractionMatrix:
             range_type = transport_costs_matrix_config["range_type"]
 
             transport_costs_matrix["source"] = transport_costs_matrix["source"].astype(int)
-            transport_costs_matrix["source"] = transport_costs_matrix["source"].map(
-                dict(enumerate(customer_origins_ids))
-                )
+            transport_costs_matrix["source"] = transport_costs_matrix["source"].map(dict(enumerate(customer_origins_ids)))
             
             transport_costs_matrix["destination"] = transport_costs_matrix["destination"].astype(int)
-            transport_costs_matrix["destination"] = transport_costs_matrix["destination"].map(
-                dict(enumerate(supply_locations_ids))
-                )
+            transport_costs_matrix["destination"] = transport_costs_matrix["destination"].map(dict(enumerate(supply_locations_ids)))
             
             transport_costs_matrix["source_destination"] = transport_costs_matrix["source"].astype(str)+"_"+transport_costs_matrix["destination"].astype(str)
             transport_costs_matrix = transport_costs_matrix[["source_destination", range_type]]
@@ -952,8 +1017,7 @@ class MCIModel:
         transformation = "LCT"
         ):
         
-        interaction_matrix = self.interaction_matrix
-        
+        interaction_matrix = self.interaction_matrix        
         interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
 
         if interaction_matrix_df["t_ij"].isna().all():
@@ -966,7 +1030,8 @@ class MCIModel:
             cols = ["A_j", "t_ij"]
             )
 
-        customer_origins_metadata = interaction_matrix.get_customer_origins().get_metadata()
+        customer_origins = interaction_matrix.get_customer_origins()
+        customer_origins_metadata = customer_origins.get_metadata()
         
         t_ij_weighting = customer_origins_metadata["weighting"][0]["param"]
 
@@ -975,7 +1040,8 @@ class MCIModel:
         else:
             mci_formula = f"t_ij**{t_ij_weighting}"
         
-        supply_locations_metadata = interaction_matrix.get_supply_locations().get_metadata()
+        supply_locations = interaction_matrix.get_supply_locations()
+        supply_locations_metadata = supply_locations.get_metadata()
         attraction_col = supply_locations_metadata["attraction_col"]
         attraction_weighting = supply_locations_metadata["weighting"]
 
@@ -991,17 +1057,27 @@ class MCIModel:
         if transformation == "ILCT":
             interaction_matrix_df["U_ij"] = np.exp(interaction_matrix_df["U_ij"])
 
-        self.interaction_matrix = interaction_matrix_df
+        interaction_matrix = InteractionMatrix(
+            interaction_matrix_df,
+            customer_origins,
+            supply_locations
+            )
+        self.interaction_matrix = interaction_matrix
 
         return self
     
-    def probabilities (self):
+    def probabilities (
+        self,
+        transformation = "LCT"
+        ):
 
-        interaction_matrix_df = self.interaction_matrix_df
+        interaction_matrix = self.interaction_matrix        
+        interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
 
         if interaction_matrix_df["U_ij"].isna().all():
-            self.utility()
-            interaction_matrix_df = self.interaction_matrix_df
+            self.utility(transformation = transformation)
+            interaction_matrix = self.interaction_matrix
+            interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
 
         utility_i = pd.DataFrame(interaction_matrix_df.groupby("i")["U_ij"].sum())
         utility_i = utility_i.rename(columns = {"U_ij": "U_i"})
@@ -1017,14 +1093,22 @@ class MCIModel:
 
         interaction_matrix_df = interaction_matrix_df.drop(columns=["U_i"])
 
-        self.interaction_matrix_df = interaction_matrix_df
+        interaction_matrix.interaction_matrix_df = interaction_matrix_df
+        self.interaction_matrix = interaction_matrix
 
         return self
         
-    def flows (self):
+    def flows (
+        self,
+        transformation = "LCT"
+        ):
 
-        interaction_matrix_df = self.interaction_matrix_df
+        interaction_matrix = self.interaction_matrix
+        interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
 
+        if "C_i" not in interaction_matrix_df.columns:
+            raise ValueError ("No market size column defined in interaction matrix.")
+        
         if interaction_matrix_df["C_i"].isna().all():
             raise ValueError ("Market size column in customer origins not defined. Use CustomerOrigins.define_marketsize()")
 
@@ -1034,8 +1118,9 @@ class MCIModel:
             )
 
         if interaction_matrix_df["p_ij"].isna().all():
-            self.probabilities()
-            interaction_matrix_df = self.interaction_matrix_df
+            self.probabilities(transformation=transformation)
+            interaction_matrix = self.interaction_matrix
+            interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
 
         interaction_matrix_df["E_ij"] = interaction_matrix_df["p_ij"] * interaction_matrix_df["C_i"]
 
@@ -1080,16 +1165,20 @@ def load_geodata (
     ):
 
     if location_type is None or (location_type != "origins" and location_type != "destinations"):
-        raise ValueError ("location_type must be either 'origins' or 'destinations'")
+        raise ValueError ("Argument location_type must be either 'origins' or 'destinations'")
 
     if isinstance(data, gp.GeoDataFrame):
         geodata_gpd_original = data
+        if not all(geodata_gpd_original.geometry.geom_type == "Point"):
+            raise ValueError ("Input geopandas.GeoDataFrame must be of type 'Point'")
         crs_input = geodata_gpd_original.crs
     elif isinstance(data, pd.DataFrame):
         geodata_tab = data
     elif isinstance(data, str):
         if data_type == "shp":
             geodata_gpd_original = gp.read_file(data)
+            if not all(geodata_gpd_original.geometry.geom_type == "Point"):
+                raise ValueError ("Input shapefile must be of type 'Point'")
             crs_input = geodata_gpd_original.crs
         elif data_type == "csv" or data_type == "xlsx":
             if x_col is None:
@@ -1111,6 +1200,12 @@ def load_geodata (
         raise TypeError("data must be pandas.DataFrame, geopandas.GeoDataFrame or file (.csv, .xlsx, .shp)")
 
     if data_type == "csv" or data_type == "xlsx" or (isinstance(data, pd.DataFrame) and not isinstance(data, gp.GeoDataFrame)):
+        
+        check_vars(
+            df = geodata_tab,
+            cols = [x_col, y_col]
+            )
+        
         geodata_gpd_original = gp.GeoDataFrame(
             geodata_tab, 
             geometry = gp.points_from_xy(
@@ -1146,6 +1241,7 @@ def load_geodata (
             geodata_gpd, 
             geodata_gpd_original, 
             metadata,
+            None,
             None
             )        
     elif location_type == "destinations":
@@ -1153,6 +1249,7 @@ def load_geodata (
             geodata_gpd, 
             geodata_gpd_original, 
             metadata,
+            None,
             None
             )
 
@@ -1349,7 +1446,8 @@ def load_interaction_matrix(
         geodata_gpd = customer_origins_geodata_gpd,
         geodata_gpd_original = customer_origins_geodata_original_tab,
         metadata = customer_origins_metadata,
-        isochrones_gdf = None
+        isochrones_gdf = None,
+        buffers_gdf = None
         )
 
     if supply_locations_coords_col is not None:
@@ -1415,7 +1513,8 @@ def load_interaction_matrix(
         geodata_gpd = supply_locations_geodata_gpd,
         geodata_gpd_original = supply_locations_geodata_original_tab,
         metadata = supply_locations_metadata,
-        isochrones_gdf = None
+        isochrones_gdf = None,
+        buffers_gdf = None
         )
     
     interaction_matrix_df = interaction_matrix_df.rename(
@@ -1494,7 +1593,7 @@ def get_isochrones(
     profile: str = "driving-car",
     donut: bool = True,
     ors_server: str = "https://api.openrouteservice.org/v2/",
-    ors_auth: str = None,
+    ors_auth: str = None,    
     timeout = 10,
     delay = 1,
     save_output: bool = True,
@@ -1544,6 +1643,8 @@ def get_isochrones(
         time.sleep(delay)
 
         isochrone_gdf[unique_id_col] = unique_id_values[i]
+        
+        isochrone_gdf["segment_minutes"] = isochrone_gdf["segment"]/60        
 
         isochrones_gdf = pd.concat(
             [
@@ -1555,6 +1656,9 @@ def get_isochrones(
         
         i = i+1
 
+    isochrones_gdf["segment"] = isochrones_gdf["segment"].astype(int)
+    isochrones_gdf["segment_minutes"] = isochrones_gdf["segment_minutes"].astype(int)
+    
     isochrones_gdf.set_crs(
         output_crs, 
         allow_override=True, 

huff/ors.py

@@ -4,8 +4,8 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.2.0
-# Last update: 2025-05-14 18:28
+# Version:     1.3.1
+# Last update: 2025-05-28 18:01
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
@@ -119,7 +119,6 @@ class Client:
     def isochrone(
         self,
         locations: list,
-        id: list = [],
         segments: list = [900, 600, 300],
         range_type: str = "time",
         intersections: str = "true",
@@ -130,6 +129,12 @@ class Client:
         output_crs: str = "EPSG:4326"
         ):
 
+        if len(segments) > 10:
+            raise ValueError ("ORS client does not allow >10 intervals in an Isochrones query. See https://openrouteservice.org/restrictions/.")
+        
+        if len(locations) > 5:
+            raise ValueError ("ORS client does not allow >5 locations in an Isochrones query. See https://openrouteservice.org/restrictions/.")
+    
         ors_url = self.server + "isochrones/" + profile
         auth = self.auth
 
@@ -162,9 +167,9 @@ class Client:
                 timeout=timeout
                 )
             
-        except:
+        except Exception as e:
 
-            print ("Unknown error while accessing ORS server")
+            print ("Error while accessing ORS server: ", str(e))
             
             status_code = 99999
             isochrones_gdf = None 
@@ -200,7 +205,7 @@ class Client:
 
             isochrones_gdf["segment"] = 0
             isochrones_gdf_properties_dict = dict(isochrones_gdf["properties"])
-
+            
             for i in range(len(isochrones_gdf_properties_dict)):
                 isochrones_gdf.iloc[i,3] = isochrones_gdf_properties_dict[i]["value"]
 
@@ -212,9 +217,9 @@ class Client:
                 print ("Saved as", output_filepath)
 
         else:
-
-            print ("Error while accessing ORS server. Status Code: " + str(status_code))
-
+            
+            print(f"Error while accessing ORS server. Status code: {status_code} - {response.reason}")
+            
             isochrones_gdf = None
             metadata = None
         
@@ -233,14 +238,14 @@ class Client:
         sources: list = [],
         destinations: list = [],
         id: str = None,
-        range_type = "time",
-        profile = "driving-car",
+        range_type: str = "time",
+        profile: str = "driving-car",
         metrics: list = [],
         resolve_locations: bool = False,    
         units: str = "mi",
-        timeout = 10,
-        save_output = False,
-        output_filepath = "matrix.csv",
+        timeout: int = 10,
+        save_output: bool = False,
+        output_filepath: str = "matrix.csv",
         csv_sep = ";",
         csv_decimal = ",",
         csv_encoding = None
@@ -285,9 +290,9 @@ class Client:
                 timeout=timeout
                 )
             
-        except:
-            
-            print ("Unknown error while accessing ORS server")
+        except Exception as e:
+
+            print ("Error while accessing ORS server: ", str(e))
             
             status_code = 99999
             matrix_df = None
@@ -368,7 +373,7 @@ class Client:
 
         else:
 
-            print ("Error in accessing ORS server. Status Code: " + str(status_code))
+            print(f"Error while accessing ORS server. Status code: {status_code} - {response.reason}")
 
             matrix_df = None
             metadata = None