huff 1.0.0__tar.gz → 1.1.1__tar.gz

huff-1.1.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.1
+Name: huff
+Version: 1.1.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
+
+## 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
+  - Calculating 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/
+
+## 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).
+  - 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)
+
+
+## Installation
+
+To install the package, use `pip`:
+
+```bash
+pip install huff

huff-1.1.1/README.md

@@ -0,0 +1,41 @@
+# 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
+  - Calculating 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/
+
+## 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).
+  - 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)
+
+
+## Installation
+
+To install the package, use `pip`:
+
+```bash
+pip install huff

{huff-1.0.0 → huff-1.1.1}/huff/gistools.py

@@ -4,8 +4,8 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.0.0
-# Last update: 2025-04-25 18:16
+# Version:     1.1.1
+# Last update: 2025-04-29 18:12
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 

{huff-1.0.0 → huff-1.1.1}/huff/models.py

@@ -4,8 +4,8 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.0.0
-# Last update: 2025-04-25 18:13
+# Version:     1.1.1
+# Last update: 2025-04-29 18:12
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
@@ -13,7 +13,9 @@
 import pandas as pd
 import geopandas as gp
 import numpy as np
-from .ors import matrix
+import time
+from huff.ors import Client, TimeDistanceMatrix, Isochrone
+from huff.gistools import overlay_difference
 
 
 class CustomerOrigins:
@@ -198,28 +200,142 @@ class SupplyLocations:
         self.metadata = metadata
 
         return self
+    
+    def add_new_destinations(
+        self,
+        new_destinations,
+        ):
+        
+        geodata_gpd_original = self.get_geodata_gpd_original()
+        geodata_gpd = self.get_geodata_gpd()
+        metadata = self.get_metadata()
+
+        new_destinations_gpd_original = new_destinations.get_geodata_gpd_original()
+        new_destinations_gpd = new_destinations.get_geodata_gpd()
+        new_destinations_metadata = new_destinations.get_metadata()
+
+        if list(new_destinations_gpd_original.columns) != list(geodata_gpd_original.columns):
+            raise KeyError("Supply locations and new destinations data have different column names.")
+        if list(new_destinations_gpd.columns) != list(geodata_gpd.columns):
+            raise KeyError("Supply locations and new destinations data have different column names.")
+
+        geodata_gpd_original = geodata_gpd_original.append(
+            new_destinations_gpd_original, 
+            ignore_index=True
+            )
+        
+        geodata_gpd = geodata_gpd.append(
+            new_destinations_gpd, 
+            ignore_index=True
+            )
+        
+        metadata["no_points"] = metadata["no_points"]+new_destinations_metadata["no_points"]
+        
+        self.geodata_gpd = geodata_gpd
+        self.geodata_gpd_original = geodata_gpd_original
+        self.metadata = metadata
+
+        return self
+    
+    def isochrones(
+        self,
+        segments: list = [900, 600, 300],
+        range_type: str = "time",
+        intersections: str = "true",
+        profile: str = "driving-car",
+        donut: bool = True,
+        ors_server: str = "https://api.openrouteservice.org/v2/",
+        ors_auth: str = None,
+        timeout = 10,
+        delay = 1,
+        save_output: bool = True,
+        output_filepath: str = "isochrones.shp",
+        output_crs: str = "EPSG:4326"
+        ):
+
+        geodata_gpd = self.get_geodata_gpd()
+        metadata = self.get_metadata()
+
+        coords = [(point.x, point.y) for point in geodata_gpd.geometry]
+        
+        unique_id_col = metadata["unique_id"]
+        unique_id_values = geodata_gpd[unique_id_col].values
+
+        ors_client = Client(
+            server = ors_server,
+            auth = ors_auth
+            )
+        
+        isochrones_gdf = gp.GeoDataFrame(columns=[unique_id_col, "geometry"])
+        
+        i = 0
+
+        for x, y in coords:
+            
+            isochrone_output = ors_client.isochrone(
+                locations = [[x, y]],
+                segments = segments,
+                range_type = range_type,
+                intersections = intersections,
+                profile = profile,
+                timeout = timeout,
+                save_output = False,
+                output_crs = output_crs
+                )
+            
+            if isochrone_output.status_code != 200:
+                continue        
+            
+            isochrone_gdf = isochrone_output.get_isochrones_gdf()
+            
+            if donut:
+                isochrone_gdf = overlay_difference(
+                    polygon_gdf = isochrone_gdf, 
+                    sort_col = "segment"
+                    )
+                
+            time.sleep(delay)
+
+            isochrone_gdf[unique_id_col] = unique_id_values[i]
+
+            isochrones_gdf = pd.concat(
+                [
+                    isochrones_gdf, 
+                    isochrone_gdf
+                    ], 
+                ignore_index=True
+                )
+            
+            i = i+1
+
+        isochrones_gdf.set_crs(
+            output_crs, 
+            allow_override=True, 
+            inplace=True
+            )
+            
+        if save_output:
+
+            isochrones_gdf.to_file(filename = output_filepath)
+
+        return isochrones_gdf
 
 class InteractionMatrix:
 
     def __init__(
         self, 
         interaction_matrix_df,
-        market_areas_df,
         customer_origins,
         supply_locations
         ):
 
         self.interaction_matrix_df = interaction_matrix_df
-        self.market_areas_df = market_areas_df
         self.customer_origins = customer_origins
         self.supply_locations = supply_locations
     
     def get_interaction_matrix_df(self):
         return self.interaction_matrix_df
     
-    def get_market_areas_df(self):
-        return self.market_areas_df
-
     def get_customer_origins(self):
         return self.customer_origins
 
@@ -231,7 +347,7 @@ class InteractionMatrix:
         customer_origins_metadata = self.get_customer_origins().get_metadata()
         supply_locations_metadata = self.get_supply_locations().get_metadata()
 
-        print("Huff Model")
+        print("Huff Model Interaction Matrix")
         print("----------------------------------")
         print("Supply locations   " + str(supply_locations_metadata["no_points"]))
         if supply_locations_metadata["attraction_col"][0] is None:
@@ -259,6 +375,7 @@ class InteractionMatrix:
         self,
         range_type: str = "time",
         time_unit: str = "minutes",
+        ors_server: str = "https://api.openrouteservice.org/v2/",
         ors_auth: str = None,
         save_output: bool = False,
         output_filepath: str = "transport_costs_matrix.csv"
@@ -285,8 +402,11 @@ class InteractionMatrix:
         customer_origins_index = list(range(len(customer_origins_coords)))
         locations_coords_index = list(range(len(customer_origins_index), len(locations_coords)))
     
-        time_distance_matrix = matrix(
-            auth = ors_auth,
+        ors_client = Client(
+            server = ors_server,
+            auth = ors_auth
+            )
+        time_distance_matrix = ors_client.matrix(
             locations = locations_coords,
             save_output = save_output,
             output_filepath = output_filepath, 
@@ -295,6 +415,9 @@ class InteractionMatrix:
             range_type = range_type
             )
         
+        if time_distance_matrix.get_metadata() is None:
+            raise ValueError ("No transport costs matrix was built.")
+
         transport_costs_matrix = time_distance_matrix.get_matrix()
         transport_costs_matrix_config = time_distance_matrix.get_config()
         range_type = transport_costs_matrix_config["range_type"]
@@ -339,6 +462,11 @@ class InteractionMatrix:
         if interaction_matrix_df["A_j"].isna().all():
             raise ValueError ("Attraction variable is not defined")
 
+        check_vars(
+            df = interaction_matrix_df,
+            cols = ["A_j", "t_ij"]
+            )
+        
         customer_origins = self.customer_origins
         customer_origins_metadata = customer_origins.get_metadata()
         tc_weighting = customer_origins_metadata["weighting"][0]
@@ -400,6 +528,11 @@ class InteractionMatrix:
         if interaction_matrix_df["C_i"].isna().all():
             raise ValueError ("Market size column in customer origins not defined. Use CustomerOrigins.define_marketsize()")
 
+        check_vars(
+            df = interaction_matrix_df,
+            cols = ["C_i"]
+            )
+
         if interaction_matrix_df["p_ij"].isna().all():
             self.probabilities()
             interaction_matrix_df = self.interaction_matrix_df
@@ -413,17 +546,110 @@ class InteractionMatrix:
     def marketareas (self):
 
         interaction_matrix_df = self.interaction_matrix_df
-
+        
+        check_vars(
+            df = interaction_matrix_df,
+            cols = ["E_ij"]
+            )
+        
         market_areas_df = pd.DataFrame(interaction_matrix_df.groupby("j")["E_ij"].sum())
         market_areas_df = market_areas_df.reset_index(drop=False)
         market_areas_df = market_areas_df.rename(columns={"E_ij": "T_j"})
 
-        print(market_areas_df)
+        huff_model = HuffModel(
+            self,
+            market_areas_df
+            )
+        
+        return huff_model
+
+    def mci_transformation(
+        self,
+        cols: list = ["A_j", "t_ij"]
+        ):
 
-        self.market_areas_df = market_areas_df
+        """ MCI model log-centering transformation """
+        
+        cols = cols + ["p_ij"]
+
+        interaction_matrix_df = self.interaction_matrix_df
+
+        interaction_matrix_df = mci_transformation(
+            df = interaction_matrix_df,
+            ref_col = "i",
+            cols = cols
+            )
+        
+        self.interaction_matrix_df = interaction_matrix_df
 
         return self
 
+class HuffModel:
+
+    def __init__(
+        self,
+        interaction_matrix, 
+        market_areas_df
+        ):
+
+        self.interaction_matrix = interaction_matrix
+        self.market_areas_df = market_areas_df
+
+    def get_interaction_matrix_df(self):
+
+        interaction_matrix = self.interaction_matrix
+        interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
+
+        return interaction_matrix_df
+    
+    def get_supply_locations(self):
+
+        interaction_matrix = self.interaction_matrix
+        supply_locations = interaction_matrix.get_supply_locations()
+
+        return supply_locations
+
+    def get_customer_origins(self):
+
+        interaction_matrix = self.interaction_matrix
+        customer_origins = interaction_matrix.get_customer_origins()
+
+        return customer_origins
+
+    def get_market_areas_df(self):
+        return self.market_areas_df
+    
+    def summary(self):
+
+        interaction_matrix = self.interaction_matrix
+
+        customer_origins_metadata = interaction_matrix.get_customer_origins().get_metadata()
+        supply_locations_metadata = interaction_matrix.get_supply_locations().get_metadata()
+
+        print("Huff Model")
+        print("----------------------------------")
+        print("Supply locations   " + str(supply_locations_metadata["no_points"]))
+        if supply_locations_metadata["attraction_col"][0] is None:
+            print("Attraction column  not defined")
+        else:
+            print("Attraction column  " + supply_locations_metadata["attraction_col"][0])
+        print("Customer origins   " + str(customer_origins_metadata["no_points"]))
+        if customer_origins_metadata["marketsize_col"] is None:
+            print("Market size column not defined")
+        else:
+            print("Market size column " + customer_origins_metadata["marketsize_col"])
+        print("----------------------------------")
+        print("Weights")
+        if supply_locations_metadata["weighting"][0]["func"] is None and supply_locations_metadata["weighting"][0]["param"] is None:
+            print("Gamma              not defined")
+        else:
+            print("Gamma              " + str(supply_locations_metadata["weighting"][0]["param"]) + " (" + supply_locations_metadata["weighting"][0]["func"] + ")")
+        if customer_origins_metadata["weighting"][0]["func"] is None and customer_origins_metadata["weighting"][0]["param"] is None:
+            print("Lambda             not defined")
+        else:
+            print("Lambda            " + str(customer_origins_metadata["weighting"][0]["param"]) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")     
+        print("----------------------------------")
+          
 def load_geodata (
     file, 
     location_type: str, 
@@ -438,7 +664,7 @@ def load_geodata (
     ):
 
     if location_type is None or (location_type != "origins" and location_type != "destinations"):
-        raise ValueError ("location_type must be either 'loc' or 'dest'")
+        raise ValueError ("location_type must be either 'origins' or 'destinations'")
     
     if data_type not in ["shp", "csv", "xlsx"]:
         raise ValueError ("data_type must be 'shp', 'csv' or 'xlsx'")
@@ -517,7 +743,7 @@ def create_interaction_matrix(
     if not isinstance(customer_origins, CustomerOrigins):
         raise ValueError ("customer_origins must be of class CustomerOrigins")
     if not isinstance(supply_locations, SupplyLocations):
-        raise ValueError ("supply_locations must be of class supply_locations")
+        raise ValueError ("supply_locations must be of class SupplyLocations")
 
     customer_origins_metadata = customer_origins.get_metadata()
     if customer_origins_metadata["marketsize_col"] is None:
@@ -573,13 +799,53 @@ def create_interaction_matrix(
     interaction_matrix_df["p_ij"] = None
     interaction_matrix_df["E_ij"] = None
 
-    market_areas_df = None
-
     interaction_matrix = InteractionMatrix(
         interaction_matrix_df,
-        market_areas_df,
         customer_origins,
         supply_locations
         )
          
-    return interaction_matrix
+    return interaction_matrix
+
+def check_vars(
+    df: pd.DataFrame,
+    cols: list
+    ):
+
+    for col in cols:
+        if col not in df.columns:
+            raise KeyError(f"Column '{col}' not in dataframe.")
+    
+    for col in cols:
+        if not pd.api.types.is_numeric_dtype(df[col]):
+            raise ValueError(f"Column '{col}' is not numeric. All columns must be numeric.")
+    
+    for col in cols:
+        if (df[col] <= 0).any():
+            raise ValueError(f"Column '{col}' includes values <= 0. All values must be numeric and positive.")
+
+def mci_transformation(
+    df: pd.DataFrame,
+    ref_col: str,
+    cols: list
+    ):
+   
+    check_vars(
+        df = df,
+        cols = cols + [ref_col]
+        )
+
+    def lct (x):
+
+        x_geom = np.exp(np.log(x).mean())
+        x_lct = np.log(x/x_geom)
+
+        return x_lct
+    
+    for var in cols:
+
+        var_t = df.groupby(ref_col)[var].apply(lct)
+        var_t = var_t.reset_index()
+        df[var+"_t"] = var_t[var]
+
+    return df