huff 1.2.0__tar.gz → 1.3.0__tar.gz

{huff-1.2.0 → huff-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: huff
-Version: 1.2.0
+Version: 1.3.0
 Summary: huff: Huff Model Market Area Analysis
 Author: Thomas Wieland
 Author-email: geowieland@googlemail.com
@@ -20,28 +20,39 @@ See the /tests directory for usage examples of most of the included functions.
 - **Huff Model**: 
   - Defining origins and destinations with weightings
   - Creating interaction matrix from origins and destinations
-  - Calculating basic Huff Model
+  - Market simulation with basic Huff Model
 - **Multiplicative Competitive Interaction Model**: 
-  - Log-centering transformation
-  - Fitting MCI model with >= independent variables
-- **OpenRouteService Client** (1) (Tools via API): 
-  - Creating transport costs matrix from origins and destinations
-  - Creating isochrones from destinations
-- **Tools**: 
+  - Log-centering transformation of interaction matrix
+  - Fitting MCI model with >= 2 independent variables
+  - MCI model market simulation
+- **GIS tools**:
+  - OpenRouteService Client (1):
+    - Creating transport costs matrix from origins and destinations
+    - Creating isochrones from origins and destinations
+  - OpenStreetMap Client (2):
+    - Creating simple maps with OSM basemap
+  - Other GIS tools:
+    - Creating buffers from geodata
+    - Spatial join with with statistics
+    - Creating euclidean distance matrix from origins and destinations
+    - Overlay-difference analysis of polygons
+- **Data management tools**: 
   - Loading own interaction matrix for analysis
-  - GIS tools for preparing geodata
+  - Creating origins/destinations objects from point geodata
 
-(1) Attribution of OpenRouteService:
-© openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/
+(1) © openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/
+(2) © OpenStreetMap contributors | available under the Open Database License | https://www.openstreetmap.org/
 
 ## Literature
   - Huff DL (1962) *Determination of Intra-Urban Retail Trade Areas*.
   - Huff DL (1964) Defining and estimating a trading area. *Journal of Marketing* 28(4): 34–38. [10.2307/1249154](https://doi.org/10.2307/1249154)
   - Huff DL, McCallum BM (2008) Calibrating the Huff Model using ArcGIS Business Analyst. ESRI White Paper, September 2008. https://www.esri.com/library/whitepapers/pdfs/calibrating-huff-model.pdf. 
-  - De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. *Applied Geography*,* 46(1): 80–89. [10.1016/j.apgeog.2013.09.026](https://doi.org/10.1016/j.apgeog.2013.09.026) 
+  - De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. *Applied Geography* 46(1): 80–89. [10.1016/j.apgeog.2013.09.026](https://doi.org/10.1016/j.apgeog.2013.09.026) 
   - Nakanishi M, Cooper LG (1974) Parameter estimation for a Multiplicative Competitive Interaction Model: Least squares approach. *Journal of Marketing Research* 11(3): 303–311. [10.2307/3151146](https://doi.org/10.2307/3151146).
+  - Nakanishi M, Cooper LG (1982) Technical Note — Simplified Estimation Procedures for MCI Models. *Marketing Science* 1(3): 314-322. [10.1287/mksc.1.3.314](https://doi.org/10.1287/mksc.1.3.314)
   - Wieland T (2017) Market Area Analysis for Retail and Service Locations with MCI. *R Journal* 9(1): 298-323. [10.32614/RJ-2017-020](https://doi.org/10.32614/RJ-2017-020)
   - Wieland T (2018) A Hurdle Model Approach of Store Choice and Market Area Analysis in Grocery Retailing. *Papers in Applied Geography* 4(4): 370-389. [10.1080/23754931.2018.1519458](https://doi.org/10.1080/23754931.2018.1519458)
+  - Wieland T (2023) Spatial shopping behavior during the Corona pandemic: insights from a micro-econometric store choice model for consumer electronics and furniture retailing in Germany. *Journal of Geographical Systems* 25(2): 291–326. [10.1007/s10109-023-00408-x](https://doi.org/10.1007/s10109-023-00408-x)
 
 
 ## Installation

{huff-1.2.0 → huff-1.3.0}/README.md

@@ -12,28 +12,39 @@ See the /tests directory for usage examples of most of the included functions.
 - **Huff Model**: 
   - Defining origins and destinations with weightings
   - Creating interaction matrix from origins and destinations
-  - Calculating basic Huff Model
+  - Market simulation with basic Huff Model
 - **Multiplicative Competitive Interaction Model**: 
-  - Log-centering transformation
-  - Fitting MCI model with >= independent variables
-- **OpenRouteService Client** (1) (Tools via API): 
-  - Creating transport costs matrix from origins and destinations
-  - Creating isochrones from destinations
-- **Tools**: 
+  - Log-centering transformation of interaction matrix
+  - Fitting MCI model with >= 2 independent variables
+  - MCI model market simulation
+- **GIS tools**:
+  - OpenRouteService Client (1):
+    - Creating transport costs matrix from origins and destinations
+    - Creating isochrones from origins and destinations
+  - OpenStreetMap Client (2):
+    - Creating simple maps with OSM basemap
+  - Other GIS tools:
+    - Creating buffers from geodata
+    - Spatial join with with statistics
+    - Creating euclidean distance matrix from origins and destinations
+    - Overlay-difference analysis of polygons
+- **Data management tools**: 
   - Loading own interaction matrix for analysis
-  - GIS tools for preparing geodata
+  - Creating origins/destinations objects from point geodata
 
-(1) Attribution of OpenRouteService:
-© openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/
+(1) © openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/
+(2) © OpenStreetMap contributors | available under the Open Database License | https://www.openstreetmap.org/
 
 ## Literature
   - Huff DL (1962) *Determination of Intra-Urban Retail Trade Areas*.
   - Huff DL (1964) Defining and estimating a trading area. *Journal of Marketing* 28(4): 34–38. [10.2307/1249154](https://doi.org/10.2307/1249154)
   - Huff DL, McCallum BM (2008) Calibrating the Huff Model using ArcGIS Business Analyst. ESRI White Paper, September 2008. https://www.esri.com/library/whitepapers/pdfs/calibrating-huff-model.pdf. 
-  - De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. *Applied Geography*,* 46(1): 80–89. [10.1016/j.apgeog.2013.09.026](https://doi.org/10.1016/j.apgeog.2013.09.026) 
+  - De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. *Applied Geography* 46(1): 80–89. [10.1016/j.apgeog.2013.09.026](https://doi.org/10.1016/j.apgeog.2013.09.026) 
   - Nakanishi M, Cooper LG (1974) Parameter estimation for a Multiplicative Competitive Interaction Model: Least squares approach. *Journal of Marketing Research* 11(3): 303–311. [10.2307/3151146](https://doi.org/10.2307/3151146).
+  - Nakanishi M, Cooper LG (1982) Technical Note — Simplified Estimation Procedures for MCI Models. *Marketing Science* 1(3): 314-322. [10.1287/mksc.1.3.314](https://doi.org/10.1287/mksc.1.3.314)
   - Wieland T (2017) Market Area Analysis for Retail and Service Locations with MCI. *R Journal* 9(1): 298-323. [10.32614/RJ-2017-020](https://doi.org/10.32614/RJ-2017-020)
   - Wieland T (2018) A Hurdle Model Approach of Store Choice and Market Area Analysis in Grocery Retailing. *Papers in Applied Geography* 4(4): 370-389. [10.1080/23754931.2018.1519458](https://doi.org/10.1080/23754931.2018.1519458)
+  - Wieland T (2023) Spatial shopping behavior during the Corona pandemic: insights from a micro-econometric store choice model for consumer electronics and furniture retailing in Germany. *Journal of Geographical Systems* 25(2): 291–326. [10.1007/s10109-023-00408-x](https://doi.org/10.1007/s10109-023-00408-x)
 
 
 ## Installation

huff-1.3.0/huff/gistools.py

@@ -0,0 +1,216 @@
+#-----------------------------------------------------------------------
+# Name:        gistools (huff package)
+# Purpose:     GIS tools
+# Author:      Thomas Wieland 
+#              ORCID: 0000-0001-5168-9846
+#              mail: geowieland@googlemail.com              
+# Version:     1.3.0
+# Last update: 2025-05-22 05:44
+# 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
+
+
+def distance_matrix(
+    sources: list,
+    destinations: list,
+    unit: str = "m",
+    ):
+
+    def euclidean_distance (
+        source: list,
+        destination: list,
+        unit: str = "m"
+        ):
+
+        lon1 = source[0]
+        lat1 = source[1]
+        lon2 = destination[0]
+        lat2 = destination[1]
+
+        lat1_r = lat1*pi/180
+        lon1_r = lon1*pi/180
+        lat2_r = lat2*pi/180
+        lon2_r = lon2*pi/180
+
+        distance = 6378 * (acos(sin(lat1_r) * sin(lat2_r) + cos(lat1_r) * cos(lat2_r) * cos(lon2_r - lon1_r)))
+        if unit == "m": 
+            distance = distance*1000
+        if unit == "mile": 
+            distance = distance/1.60934
+
+        return distance
+
+    matrix = []
+
+    for source in sources:
+        row = []
+        for destination in destinations:
+            dist = euclidean_distance(
+                source, 
+                destination, 
+                unit
+                )
+            row.append(dist)
+        matrix.append(row)
+
+    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,
+    ):
+
+    if sort_col is not None:
+        polygon_gdf = polygon_gdf.sort_values(by=sort_col).reset_index(drop=True)
+    else:
+        polygon_gdf = polygon_gdf.reset_index(drop=True)
+
+    new_geometries = []
+    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)
+
+        if difference_polygon.is_empty or not difference_polygon.is_valid:
+            continue
+
+        new_geometries.append(difference_polygon)
+        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"))
+
+    polygon_gdf_difference = gp.GeoDataFrame(
+        new_data, geometry=new_geometries, crs=polygon_gdf.crs
+    )
+
+    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-1.2.0 → huff-1.3.0}/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.0
+# Last update: 2025-05-22 05:45
 # 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):
 
@@ -52,6 +54,10 @@ class CustomerOrigins:
 
         return self.isochrones_gdf
 
+    def get_buffers(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]]
@@ -1080,16 +1145,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 +1180,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 +1221,7 @@ def load_geodata (
             geodata_gpd, 
             geodata_gpd_original, 
             metadata,
+            None,
             None
             )        
     elif location_type == "destinations":
@@ -1153,6 +1229,7 @@ def load_geodata (
             geodata_gpd, 
             geodata_gpd_original, 
             metadata,
+            None,
             None
             )
 
@@ -1349,7 +1426,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 +1493,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(

{huff-1.2.0 → huff-1.3.0}/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.2.1
+# Last update: 2025-05-22 05:46
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
@@ -162,9 +162,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 
@@ -212,9 +212,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 +233,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 +285,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 +368,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

huff-1.3.0/huff/osm.py

@@ -0,0 +1,207 @@
+#-----------------------------------------------------------------------
+# Name:        osm (huff package)
+# Purpose:     Helper functions for OpenStreetMap API
+# Author:      Thomas Wieland 
+#              ORCID: 0000-0001-5168-9846
+#              mail: geowieland@googlemail.com              
+# Version:     1.0.0
+# Last update: 2025-05-22 05:46
+# Copyright (c) 2025 Thomas Wieland
+#-----------------------------------------------------------------------
+
+
+import pandas as pd
+import geopandas as gpd
+import math
+import requests
+import tempfile
+import time
+import os
+from PIL import Image
+import matplotlib.pyplot as plt
+import contextily as cx
+from shapely.geometry import box
+
+
+class Client:
+
+    def __init__(
+        self,
+        server = "http://a.tile.openstreetmap.org/",
+        headers = {
+           'User-Agent': 'huff.osm/1.0.0 (your_name@your_email_provider.com)'
+           }
+        ):
+        
+        self.server = server
+        self.headers = headers
+
+    def download_tile(
+        self,
+        zoom, 
+        x, 
+        y,
+        timeout = 10
+        ):
+
+        osm_url = self.server + f"{zoom}/{x}/{y}.png"
+       
+        response = requests.get(
+            osm_url, 
+            headers = self.headers,
+            timeout = timeout
+            )
+
+        if response.status_code == 200:
+
+            with tempfile.NamedTemporaryFile(delete=False, suffix='.png') as tmp_file:
+                tmp_file.write(response.content)
+                tmp_file_path = tmp_file.name
+            return Image.open(tmp_file_path)
+        
+        else:
+
+            print(f"Error while accessing OSM server. Status code: {response.status_code} - {response.reason}")
+
+            return None
+    
+
+def get_basemap(
+    sw_lat, 
+    sw_lon, 
+    ne_lat, 
+    ne_lon, 
+    zoom = 15
+    ):
+
+    def lat_lon_to_tile(
+        lat, 
+        lon, 
+        zoom
+        ):
+
+        n = 2 ** zoom
+        x = int(n * ((lon + 180) / 360))
+        y = int(n * (1 - (math.log(math.tan(math.radians(lat)) + 1 / math.cos(math.radians(lat))) / math.pi)) / 2)
+        return x, y
+
+    def stitch_tiles(
+        zoom, 
+        sw_lat, 
+        sw_lon, 
+        ne_lat, 
+        ne_lon,
+        delay = 0.1
+        ):
+
+        osm_client = Client(
+            server = "http://a.tile.openstreetmap.org/"
+            )
+        
+        sw_x_tile, sw_y_tile = lat_lon_to_tile(sw_lat, sw_lon, zoom)
+        ne_x_tile, ne_y_tile = lat_lon_to_tile(ne_lat, ne_lon, zoom)
+
+        tile_size = 256
+        width = (ne_x_tile - sw_x_tile + 1) * tile_size
+        height = (sw_y_tile - ne_y_tile + 1) * tile_size
+
+        stitched_image = Image.new('RGB', (width, height))
+        
+        for x in range(sw_x_tile, ne_x_tile + 1):
+            for y in range(ne_y_tile, sw_y_tile + 1):
+                tile = osm_client.download_tile(
+                    zoom = zoom, 
+                    x = x, 
+                    y = y
+                    )
+                if tile:
+                    
+                    stitched_image.paste(tile, ((x - sw_x_tile) * tile_size, (sw_y_tile - y) * tile_size))
+                else:
+                    print(f"Error while retrieving tile {x}, {y}.")
+
+                time.sleep(delay)
+        
+        return stitched_image
+    
+    stitched_image = stitch_tiles(zoom, sw_lat, sw_lon, ne_lat, ne_lon)
+
+    if stitched_image:
+
+        stitched_image_path = "osm_map.png"
+        stitched_image.save(stitched_image_path)
+
+    else:
+        print("Error while building stitched images")
+
+
+def map_with_basemap(
+    layers: list,
+    osm_basemap: bool = True,
+    zoom: int = 15,
+    styles: dict = {},
+    save_output: bool = True,
+    output_filepath: str = "osm_map_with_basemap.png",
+    output_dpi = 300
+    ):
+
+    if not layers:
+        raise ValueError("List layers is empty")
+
+    combined = gpd.GeoDataFrame(
+        pd.concat(
+            layers, 
+            ignore_index = True
+            ),
+        crs = layers[0].crs
+    )
+
+    combined_wgs84 = combined.to_crs(epsg=4326)
+    bounds = combined_wgs84.total_bounds
+
+    sw_lon, sw_lat, ne_lon, ne_lat = bounds[0]*0.9999, bounds[1]*0.9999, bounds[2]*1.0001, bounds[3]*1.0001
+    
+    if osm_basemap:
+
+        get_basemap(sw_lat, sw_lon, ne_lat, ne_lon, zoom=zoom)
+
+    fig, ax = plt.subplots(figsize=(10, 10))
+
+    if osm_basemap:
+
+        img = Image.open("osm_map.png")
+        extent_img = [sw_lon, ne_lon, sw_lat, ne_lat]
+        ax.imshow(img, extent=extent_img, origin="upper")
+
+    for layer in layers:
+        layer_3857 = layer.to_crs(epsg=3857)
+        layer_3857.plot(ax=ax, alpha=0.6)
+
+    bbox = box(sw_lon, sw_lat, ne_lon, ne_lat)
+    extent_geom = gpd.GeoSeries([bbox], crs=4326).to_crs(epsg=3857).total_bounds
+
+    ax.set_xlim(extent_geom[0], extent_geom[2])
+    ax.set_ylim(extent_geom[1], extent_geom[3])
+
+    if osm_basemap:
+        cx.add_basemap(
+            ax, 
+            source=cx.providers.OpenStreetMap.Mapnik, 
+            zoom=zoom
+        )
+
+    plt.axis('off')
+    plt.show()
+    
+    if save_output:
+        
+        plt.savefig(
+            output_filepath, 
+            dpi = output_dpi, 
+            bbox_inches="tight"
+            )
+        
+        plt.close()
+
+    if os.path.exists("osm_map.png"):
+        os.remove("osm_map.png")

{huff-1.2.0 → huff-1.3.0}/huff/tests/tests_huff.py

@@ -4,13 +4,16 @@
 # 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.0
+# Last update: 2025-05-22 05:41
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
 
 from huff.models import create_interaction_matrix, get_isochrones, load_geodata, load_interaction_matrix
+from huff.osm import map_with_basemap
+from huff.gistools import buffers, point_spatial_join
+
 
 # Customer origins (statistical districts):
 
@@ -21,6 +24,14 @@ Haslach = load_geodata(
     )
 # Loading customer origins (shapefile)
 
+Haslach_buf = Haslach.buffers(
+    segments_distance=[500,1000,1500],
+    save_output=True,
+    output_filepath="Haslach_buf.shp",
+    output_crs="EPSG:31467"
+    )
+# Buffers for customer origins
+
 Haslach.summary()
 # Summary of customer origins
 
@@ -56,22 +67,24 @@ Haslach_supermarkets.define_attraction_weighting(
     )
 # Define attraction weighting (gamma)
 
-# Haslach_supermarkets.isochrones(
-#     segments_minutes=[5, 10, 15],
-#     profile = "driving-car",
-#     save_output=True,
-#     ors_auth="5b3ce3597851110001cf62480a15aafdb5a64f4d91805929f8af6abd",
-#     output_filepath="Haslach_supermarkets_iso.shp"
-#     )
-# # Obtaining isochrones for driving by car (5, 10 and 15 minutes)
+Haslach_supermarkets.isochrones(
+    segments_minutes=[5, 10],
+    profile = "foot-walking",
+    save_output=True,
+    ors_auth="5b3ce3597851110001cf62480a15aafdb5a64f4d91805929f8af6abd",
+    output_filepath="Haslach_supermarkets_iso.shp",
+    output_crs="EPSG:31467"
+    )
+# Obtaining isochrones for walking (5 and 10 minutes)
+# ORS API documentation: https://openrouteservice.org/dev/#/api-docs/v2/
 
-# Haslach_supermarkets.summary()
-# # Summary of updated customer origins
+Haslach_supermarkets.summary()
+# Summary of updated customer origins
 
-# Haslach_supermarkets_isochrones = Haslach_supermarkets.get_isochrones_gdf()
-# # Extracting isochrones
+Haslach_supermarkets_isochrones = Haslach_supermarkets.get_isochrones_gdf()
+# Extracting isochrones
 
-# print(Haslach_supermarkets_isochrones)
+print(Haslach_supermarkets_isochrones)
 
 
 # Using customer origins and supply locations for building interaction matrix:
@@ -83,10 +96,11 @@ haslach_interactionmatrix = create_interaction_matrix(
 # Creating interaction matrix
 
 interaction_matrix = haslach_interactionmatrix.transport_costs(
-    #ors_auth="5b3ce3597851110001cf62480a15aafdb5a64f4d91805929f8af6abd"
-    network=False
+    ors_auth="5b3ce3597851110001cf62480a15aafdb5a64f4d91805929f8af6abd"
+    #network=False
     )
 # Obtaining transport costs (default: driving-car)
+# ORS API documentation: https://openrouteservice.org/dev/#/api-docs/v2/
 
 interaction_matrix = interaction_matrix.flows()
 # Calculating spatial flows
@@ -120,6 +134,7 @@ mci_fit.get_market_areas_df()
 
 
 # Loading own interaction matrix:
+# Data source: Wieland 2015 (https://nbn-resolving.org/urn:nbn:de:bvb:20-opus-180753)
 
 Wieland2015_interaction_matrix = load_interaction_matrix(
     data="data/Wieland2015.xlsx",
@@ -134,7 +149,6 @@ Wieland2015_interaction_matrix = load_interaction_matrix(
     probabilities_col="MA",
     data_type="xlsx"
     )
-# Data source: Wieland 2015 (https://nbn-resolving.org/urn:nbn:de:bvb:20-opus-180753)
 
 Wieland2015_interaction_matrix.summary()
 # Summary of interaction matrix
@@ -150,4 +164,44 @@ Wieland2015_fit = Wieland2015_interaction_matrix.mci_fit(
 # Fitting MCI model with four independent variables
 
 Wieland2015_fit.summary()
-# MCI model summary
+# MCI model summary
+
+
+# Buffer analysis:
+
+Haslach_supermarkets_gdf = Haslach_supermarkets.get_geodata_gpd_original()
+Haslach_buffers = Haslach_buf.get_buffers()
+# Extracting points and buffer polygons
+
+spj_test = point_spatial_join(
+    polygon_gdf = Haslach_buffers,
+    point_gdf = Haslach_supermarkets_gdf,
+    polygon_ref_cols = ["BEZEICHN", "segment"],
+    point_stat_col = "VKF_qm"
+)
+# Spatial join with buffers and points
+# Statistics for supermarkets by statistical districts
+
+spj_test[0].to_file("spj_test.shp")
+# Save joined points as shapefile
+
+print(spj_test[1])
+# Showing df with overlay statistics
+
+
+# Creating map:
+
+Haslach_gdf = Haslach.get_geodata_gpd_original()
+Haslach_supermarkets_gdf = Haslach_supermarkets.get_geodata_gpd_original()
+Haslach_supermarkets_gdf_iso = Haslach_supermarkets.get_isochrones_gdf()
+# Extracttion geopandas.GeoDataFrames
+
+map_with_basemap(
+    layers = [
+        Haslach_supermarkets_gdf_iso,
+        Haslach_gdf, 
+        Haslach_supermarkets_gdf
+        ],
+    output_filepath = "Haslach_map.png"
+    )
+# Map with three layers and OSM basemap

{huff-1.2.0 → huff-1.3.0}/huff.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: huff
-Version: 1.2.0
+Version: 1.3.0
 Summary: huff: Huff Model Market Area Analysis
 Author: Thomas Wieland
 Author-email: geowieland@googlemail.com
@@ -20,28 +20,39 @@ See the /tests directory for usage examples of most of the included functions.
 - **Huff Model**: 
   - Defining origins and destinations with weightings
   - Creating interaction matrix from origins and destinations
-  - Calculating basic Huff Model
+  - Market simulation with basic Huff Model
 - **Multiplicative Competitive Interaction Model**: 
-  - Log-centering transformation
-  - Fitting MCI model with >= independent variables
-- **OpenRouteService Client** (1) (Tools via API): 
-  - Creating transport costs matrix from origins and destinations
-  - Creating isochrones from destinations
-- **Tools**: 
+  - Log-centering transformation of interaction matrix
+  - Fitting MCI model with >= 2 independent variables
+  - MCI model market simulation
+- **GIS tools**:
+  - OpenRouteService Client (1):
+    - Creating transport costs matrix from origins and destinations
+    - Creating isochrones from origins and destinations
+  - OpenStreetMap Client (2):
+    - Creating simple maps with OSM basemap
+  - Other GIS tools:
+    - Creating buffers from geodata
+    - Spatial join with with statistics
+    - Creating euclidean distance matrix from origins and destinations
+    - Overlay-difference analysis of polygons
+- **Data management tools**: 
   - Loading own interaction matrix for analysis
-  - GIS tools for preparing geodata
+  - Creating origins/destinations objects from point geodata
 
-(1) Attribution of OpenRouteService:
-© openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/
+(1) © openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors | https://openrouteservice.org/
+(2) © OpenStreetMap contributors | available under the Open Database License | https://www.openstreetmap.org/
 
 ## Literature
   - Huff DL (1962) *Determination of Intra-Urban Retail Trade Areas*.
   - Huff DL (1964) Defining and estimating a trading area. *Journal of Marketing* 28(4): 34–38. [10.2307/1249154](https://doi.org/10.2307/1249154)
   - Huff DL, McCallum BM (2008) Calibrating the Huff Model using ArcGIS Business Analyst. ESRI White Paper, September 2008. https://www.esri.com/library/whitepapers/pdfs/calibrating-huff-model.pdf. 
-  - De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. *Applied Geography*,* 46(1): 80–89. [10.1016/j.apgeog.2013.09.026](https://doi.org/10.1016/j.apgeog.2013.09.026) 
+  - De Beule M, Van den Poel D, Van de Weghe N (2014) An extended Huff-model for robustly benchmarking and predicting retail network performance. *Applied Geography* 46(1): 80–89. [10.1016/j.apgeog.2013.09.026](https://doi.org/10.1016/j.apgeog.2013.09.026) 
   - Nakanishi M, Cooper LG (1974) Parameter estimation for a Multiplicative Competitive Interaction Model: Least squares approach. *Journal of Marketing Research* 11(3): 303–311. [10.2307/3151146](https://doi.org/10.2307/3151146).
+  - Nakanishi M, Cooper LG (1982) Technical Note — Simplified Estimation Procedures for MCI Models. *Marketing Science* 1(3): 314-322. [10.1287/mksc.1.3.314](https://doi.org/10.1287/mksc.1.3.314)
   - Wieland T (2017) Market Area Analysis for Retail and Service Locations with MCI. *R Journal* 9(1): 298-323. [10.32614/RJ-2017-020](https://doi.org/10.32614/RJ-2017-020)
   - Wieland T (2018) A Hurdle Model Approach of Store Choice and Market Area Analysis in Grocery Retailing. *Papers in Applied Geography* 4(4): 370-389. [10.1080/23754931.2018.1519458](https://doi.org/10.1080/23754931.2018.1519458)
+  - Wieland T (2023) Spatial shopping behavior during the Corona pandemic: insights from a micro-econometric store choice model for consumer electronics and furniture retailing in Germany. *Journal of Geographical Systems* 25(2): 291–326. [10.1007/s10109-023-00408-x](https://doi.org/10.1007/s10109-023-00408-x)
 
 
 ## Installation

{huff-1.2.0 → huff-1.3.0}/huff.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ huff/__init__.py
 huff/gistools.py
 huff/models.py
 huff/ors.py
+huff/osm.py
 huff.egg-info/PKG-INFO
 huff.egg-info/SOURCES.txt
 huff.egg-info/dependency_links.txt

huff-1.3.0/huff.egg-info/requires.txt

@@ -0,0 +1,10 @@
+geopandas
+pandas
+numpy
+statsmodels
+shapely
+requests
+matplotlib
+pillow
+contextily
+openpyxl

{huff-1.2.0 → huff-1.3.0}/setup.py

@@ -7,7 +7,7 @@ def read_README():
     
 setup(
     name='huff',
-    version='1.2.0',
+    version='1.3.0',
     description='huff: Huff Model Market Area Analysis',
     packages=find_packages(include=["huff", "huff.tests"]),
     include_package_data=True,
@@ -23,10 +23,13 @@ setup(
         'geopandas',
         'pandas',
         'numpy',
-        'time',
         'statsmodels',
         'shapely',
-        'request'
+        'requests',
+        'matplotlib',
+        'pillow',
+        'contextily',
+        'openpyxl'
     ],
     test_suite='tests',
 )

huff-1.2.0/huff/gistools.py

@@ -1,96 +0,0 @@
-#-----------------------------------------------------------------------
-# Name:        gistools (huff package)
-# Purpose:     GIS tools
-# Author:      Thomas Wieland 
-#              ORCID: 0000-0001-5168-9846
-#              mail: geowieland@googlemail.com              
-# Version:     1.2.0
-# Last update: 2025-05-14 18:28
-# Copyright (c) 2025 Thomas Wieland
-#-----------------------------------------------------------------------
-
-
-import geopandas as gp
-from math import pi, sin, cos, acos
-
-
-def distance_matrix(
-    sources: list,
-    destinations: list,
-    unit: str = "m",
-    ):
-
-    def euclidean_distance (
-        source: list,
-        destination: list,
-        unit: str = "m"
-        ):
-
-        lon1 = source[0]
-        lat1 = source[1]
-        lon2 = destination[0]
-        lat2 = destination[1]
-
-        lat1_r = lat1*pi/180
-        lon1_r = lon1*pi/180
-        lat2_r = lat2*pi/180
-        lon2_r = lon2*pi/180
-
-        distance = 6378 * (acos(sin(lat1_r) * sin(lat2_r) + cos(lat1_r) * cos(lat2_r) * cos(lon2_r - lon1_r)))
-        if unit == "m": 
-            distance = distance*1000
-        if unit == "mile": 
-            distance = distance/1.60934
-
-        return distance
-
-    matrix = []
-
-    for source in sources:
-        row = []
-        for destination in destinations:
-            dist = euclidean_distance(
-                source, 
-                destination, 
-                unit
-                )
-            row.append(dist)
-        matrix.append(row)
-
-    return matrix
-
-
-def overlay_difference(
-    polygon_gdf: gp.GeoDataFrame, 
-    sort_col: str = None,
-    ):
-
-    if sort_col is not None:
-        polygon_gdf = polygon_gdf.sort_values(by=sort_col).reset_index(drop=True)
-    else:
-        polygon_gdf = polygon_gdf.reset_index(drop=True)
-
-    new_geometries = []
-    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)
-
-        if difference_polygon.is_empty or not difference_polygon.is_valid:
-            continue
-
-        new_geometries.append(difference_polygon)
-        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"))
-
-    polygon_gdf_difference = gp.GeoDataFrame(
-        new_data, geometry=new_geometries, crs=polygon_gdf.crs
-    )
-
-    return polygon_gdf_difference

huff-1.2.0/huff.egg-info/requires.txt

@@ -1,7 +0,0 @@
-geopandas
-pandas
-numpy
-time
-statsmodels
-shapely
-request