huff 1.1.2__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: huff
-Version: 1.1.2
+Version: 1.3.0
 Summary: huff: Huff Model Market Area Analysis
 Author: Thomas Wieland
 Author-email: geowieland@googlemail.com
@@ -20,26 +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
-- **OpenRouteService Client** (Tools via API): 
-  - Creating transport costs matrix from origins and destinations
-  - Creating isochrones from destinations
-
-Attribution of OpenRouteService:
-© openrouteservice.org by HeiGIT | Map data © OpenStreetMap contributors
-
-Visit https://openrouteservice.org/
+  - 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
+  - Creating origins/destinations objects from point geodata
+
+(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/README.md

@@ -0,0 +1,55 @@
+# huff: Huff Model Market Area Analysis
+
+## Author
+
+Thomas Wieland [ORCID](https://orcid.org/0000-0001-5168-9846) [EMail](mailto:geowieland@googlemail.com) 
+
+See the /tests directory for usage examples of most of the included functions.
+
+
+## Features
+
+- **Huff Model**: 
+  - Defining origins and destinations with weightings
+  - Creating interaction matrix from origins and destinations
+  - Market simulation with basic Huff Model
+- **Multiplicative Competitive Interaction Model**: 
+  - 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
+  - Creating origins/destinations objects from point geodata
+
+(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) 
+  - 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
+
+To install the package, use `pip`:
+
+```bash
+pip install huff

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
+        ]