huff 1.2.0__tar.gz → 1.3.1__tar.gz

huff-1.3.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.1
+Name: huff
+Version: 1.3.1
+Summary: huff: Huff Model Market Area Analysis
+Author: Thomas Wieland
+Author-email: geowieland@googlemail.com
+Description-Content-Type: text/markdown
+
+# huff: Huff Model Market Area Analysis
+
+This Python library is designed for performing market area analyses with the Huff Model (Huff 1962, 1964) and/or the Multiplicative Competitive Interaction (MCI) Model (Nakanishi and Cooper 1974, 1982). Users may load point shapefiles (or CSV, XLSX) of customer origins and supply locations and conduct a market area analysis step by step. The package also includes supplementary GIS functions, including clients for OpenRouteService(1) for network analysis (e.g., transport cost matrix) and OpenStreetMap(2) for simple maps. See Huff and McCallum (2008) or Wieland (2017) for a description of the models and their practical application. 
+
+
+## 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(1) Client:
+    - Creating transport costs matrix from origins and destinations
+    - Creating isochrones from origins and destinations
+  - OpenStreetMap(2) Client:
+    - 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.1/README.md

@@ -0,0 +1,60 @@
+# huff: Huff Model Market Area Analysis
+
+This Python library is designed for performing market area analyses with the Huff Model (Huff 1962, 1964) and/or the Multiplicative Competitive Interaction (MCI) Model (Nakanishi and Cooper 1974, 1982). Users may load point shapefiles (or CSV, XLSX) of customer origins and supply locations and conduct a market area analysis step by step. The package also includes supplementary GIS functions, including clients for OpenRouteService(1) for network analysis (e.g., transport cost matrix) and OpenStreetMap(2) for simple maps. See Huff and McCallum (2008) or Wieland (2017) for a description of the models and their practical application. 
+
+
+## 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(1) Client:
+    - Creating transport costs matrix from origins and destinations
+    - Creating isochrones from origins and destinations
+  - OpenStreetMap(2) Client:
+    - 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.1/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.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
+
+
+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
+        ]