huff 1.4.1__py3-none-any.whl → 1.5.0__py3-none-any.whl

huff/models.py

@@ -4,8 +4,8 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.4.1
-# Last update: 2025-06-16 17:43
+# Version:     1.5.0
+# Last update: 2025-06-25 18:32
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
@@ -119,6 +119,24 @@ class CustomerOrigins:
         param_lambda = -2
         ):
 
+        """
+        metadata["weighting"] = {
+            0: {
+                "name": "t_ij",
+                "func": "power",
+                "param": -2
+            }
+        }
+        
+        metadata["weighting"] = {
+            0: {
+                "name": "t_ij",
+                "func": "logistic",
+                "param": [10, -0.5]
+            }
+        }
+        """
+                
         metadata = self.metadata
 
         if func not in ["power", "exponential", "logistic"]:
@@ -130,6 +148,7 @@ class CustomerOrigins:
         if isinstance(param_lambda, (int, float)) and func == "logistic":
             raise ValueError("Function type "+ func + " requires two parameters in a list")
         
+        metadata["weighting"][0]["name"] = "t_ij"
         metadata["weighting"][0]["func"] = func
 
         if isinstance(param_lambda, list):
@@ -299,8 +318,10 @@ class SupplyLocations:
         if metadata["attraction_col"] is None:
             raise ValueError ("Attraction column is not yet defined. Use SupplyLocations.define_attraction()")
         
+        metadata["weighting"][0]["name"] = "A_j"
         metadata["weighting"][0]["func"] = func
         metadata["weighting"][0]["param"] = float(param_gamma)
+        
         self.metadata = metadata
 
         return self
@@ -323,6 +344,7 @@ class SupplyLocations:
         metadata["attraction_col"] = metadata["attraction_col"] + [var] 
 
         metadata["weighting"][new_key] = {
+            "name": var,
             "func": func,
             "param": param
             }
@@ -490,20 +512,19 @@ class InteractionMatrix:
         else:
             print("Market size column  " + customer_origins_metadata["marketsize_col"])
 
-        if interaction_matrix_metadata != {}:
-            if "transport_costs" in interaction_matrix_metadata:
-                print("----------------------------------")
-                if interaction_matrix_metadata["transport_costs"]["network"]:
-                    print("Transport cost type Time")
-                    print("Transport cost unit " + interaction_matrix_metadata["transport_costs"]["time_unit"])
-                else:
-                    print("Transport cost type Distance")
-                    print("Transport cost unit " + interaction_matrix_metadata["transport_costs"]["distance_unit"])
+        if interaction_matrix_metadata != {} and "transport_costs" in interaction_matrix_metadata:
+            print("----------------------------------")
+            if interaction_matrix_metadata["transport_costs"]["network"]:
+                print("Transport cost type Time")
+                print("Transport cost unit " + interaction_matrix_metadata["transport_costs"]["time_unit"])
+            else:
+                print("Transport cost type Distance")
+                print("Transport cost unit " + interaction_matrix_metadata["transport_costs"]["distance_unit"])
 
         print("----------------------------------")
         print("Partial utilities")
         print("                    Weights")
-        
+
         if supply_locations_metadata["weighting"][0]["func"] is None and supply_locations_metadata["weighting"][0]["param"] is None:
             print("Attraction          not defined")
         else:
@@ -515,9 +536,37 @@ class InteractionMatrix:
             print("Transport costs    " + str(round(customer_origins_metadata["weighting"][0]["param"],3)) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")
         elif customer_origins_metadata["weighting"][0]["func"] == "logistic":
             print("Transport costs    " + str(round(customer_origins_metadata["weighting"][0]["param"][0],3)) + ", " + str(round(customer_origins_metadata["weighting"][0]["param"][1],3)) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")
+      
+
+        attrac_vars = supply_locations_metadata["attraction_col"]
+        attrac_vars_no = len(attrac_vars)
+        
+        if attrac_vars_no > 1:
+                        
+            for key, attrac_var in enumerate(attrac_vars):
+                
+                if key == 0:
+                    continue
+                
+                if key not in supply_locations_metadata["weighting"].keys():
+                    
+                    print(f"{attrac_vars[key][:16]:16}    not defined")
+                    
+                else:
+
+                    name = supply_locations_metadata["weighting"][key]["name"]
+                    param = supply_locations_metadata["weighting"][key]["param"]
+                    func = supply_locations_metadata["weighting"][key]["func"]
+
+                    print(f"{name[:16]:16}    {round(param, 3)} ({func})")
 
         print("----------------------------------")
 
+        if interaction_matrix_metadata != {} and "fit" in interaction_matrix_metadata and interaction_matrix_metadata["fit"]["function"] is not None:
+            print("Parameter estimation")
+            print("Fit function        " + interaction_matrix_metadata["fit"]["function"])
+            print("Fit by              " + interaction_matrix_metadata["fit"]["fit_by"])
+
     def transport_costs(
         self,
         network: bool = True,
@@ -630,12 +679,73 @@ class InteractionMatrix:
 
         return self
     
+    def define_weightings(
+        self,
+        vars_funcs: dict
+        ):
+        
+        """
+        vars_funcs = {
+            0: {
+                "name": "A_j",
+                "func": "power"
+            },
+            1: {
+                "name": "t_ij",
+                "func": "logistic"
+            },
+            2: {
+                "name": "second_attraction_variable",
+                "func": "power"
+            },
+            3: {
+                "name": "third_attraction_variable",
+                "func": "exponential"
+            },
+            ...
+        }
+        """
+
+        supply_locations_metadata = self.supply_locations.metadata
+        customer_origins_metadata = self.customer_origins.metadata
+
+        supply_locations_metadata["weighting"][0]["name"] = vars_funcs[0]["name"]
+        supply_locations_metadata["weighting"][0]["func"] = vars_funcs[0]["func"]
+    
+        customer_origins_metadata["weighting"][0]["name"] = vars_funcs[1]["name"]
+        customer_origins_metadata["weighting"][0]["func"] = vars_funcs[1]["func"]
+
+        if len(vars_funcs) > 2:
+            
+            for key, var in vars_funcs.items():
+
+                if key < 2:
+                    continue
+                
+                if key not in supply_locations_metadata["weighting"]:
+                    supply_locations_metadata["weighting"][key-1] = {
+                        "name": "attrac"+str(key),
+                        "func": "power",
+                        "param": None
+                        }
+
+                supply_locations_metadata["weighting"][key-1]["name"] = var["name"]
+                supply_locations_metadata["weighting"][key-1]["func"] = var["func"]
+                supply_locations_metadata["weighting"][key-1]["param"] = None
+
+        self.supply_locations.metadata = supply_locations_metadata
+        self.customer_origins.metadata = customer_origins_metadata
+
     def utility(self):
         
         interaction_matrix_df = self.interaction_matrix_df
 
         interaction_matrix_metadata = self.get_metadata()
 
+        if "t_ij" not in interaction_matrix_df.columns:
+            raise ValueError ("No transport cost variable in interaction matrix")
+        if "A_j" not in interaction_matrix_df.columns:
+            raise ValueError ("No attraction variable in interaction matrix")
         if interaction_matrix_df["t_ij"].isna().all():
             raise ValueError ("Transport cost variable is not defined")
         if interaction_matrix_df["A_j"].isna().all():
@@ -670,6 +780,33 @@ class InteractionMatrix:
         else:
             raise ValueError ("Attraction weighting is not defined.")
         
+        attrac_vars = supply_locations_metadata["attraction_col"]
+        attrac_vars_no = len(attrac_vars)
+        attrac_var_key = 0
+
+        if attrac_vars_no > 1:
+            
+            for key, attrac_var in enumerate(attrac_vars):
+                
+                attrac_var_key = key #+1
+                if attrac_var_key == 0: #1:
+                    continue
+                
+                name = supply_locations_metadata["weighting"][attrac_var_key]["name"]
+                param = supply_locations_metadata["weighting"][attrac_var_key]["param"]
+                func = supply_locations_metadata["weighting"][attrac_var_key]["func"]
+
+                if func == "power":
+                    interaction_matrix_df[name+"_weighted"] = interaction_matrix_df[name] ** param
+                elif func == "exponential":
+                    interaction_matrix_df[name+"_weighted"] = np.exp(param * interaction_matrix_df[name])
+                else:
+                    raise ValueError ("Weighting for " + name + " is not defined.")
+                
+                interaction_matrix_df["A_j_weighted"] = interaction_matrix_df["A_j_weighted"]*interaction_matrix_df[name+"_weighted"]
+
+                interaction_matrix_df = interaction_matrix_df.drop(columns=[name+"_weighted"])
+
         interaction_matrix_df["U_ij"] = interaction_matrix_df["A_j_weighted"]*interaction_matrix_df["t_ij_weighted"]
         
         interaction_matrix_df = interaction_matrix_df.drop(columns=["A_j_weighted", "t_ij_weighted"])
@@ -687,7 +824,7 @@ class InteractionMatrix:
 
         interaction_matrix_df = self.interaction_matrix_df
 
-        if interaction_matrix_df["U_ij"].isna().all():
+        if "U_ij" not in interaction_matrix_df.columns or interaction_matrix_df["U_ij"].isna().all():
             self.utility()
             interaction_matrix_df = self.interaction_matrix_df
 
@@ -713,6 +850,8 @@ class InteractionMatrix:
 
         interaction_matrix_df = self.interaction_matrix_df
 
+        if "C_i" not in interaction_matrix_df.columns:
+            raise ValueError ("No market size variable in interaction matrix")
         if interaction_matrix_df["C_i"].isna().all():
             raise ValueError ("Market size column in customer origins not defined. Use CustomerOrigins.define_marketsize()")
 
@@ -875,6 +1014,15 @@ class InteractionMatrix:
 
         customer_origins.metadata = customer_origins_metadata
         supply_locations.metadata = supply_locations_metadata
+        
+        interaction_matrix_metadata = {
+            "fit": {
+                "function": "mci_fit",
+                "fit_by": "probabilities",
+                "method": "OLS"
+                }
+            }
+               
         interaction_matrix = InteractionMatrix(
             interaction_matrix_df,
             customer_origins,
@@ -891,23 +1039,34 @@ class InteractionMatrix:
         
         return mci_model
 
-    def huff_loglik(
+    def loglik(
         self,
-        params
+        params,
+        fit_by = "probabilities"
         ):
+        
+        if fit_by not in ["probabilities", "flows"]:
+            raise ValueError ("Parameter 'fit_by' must be 'probabilities' or 'flows'")
 
         if not isinstance(params, list):
             if isinstance(params, np.ndarray):
                 params = params.tolist()
             else:
-                raise ValueError("Parameter 'params' must be a list or np.ndarray with two or three parameter values")
+                raise ValueError("Parameter 'params' must be a list or np.ndarray with at least 2 parameter values")
         
-        if len(params) == 2:
-            param_gamma, param_lambda = params
-        elif len(params) == 3:
-            param_gamma, param_lambda, param_lambda2 = params
-        else:
-            raise ValueError("Parameter 'params' must be a list with two or three parameter values")        
+        if len(params) < 2:
+            raise ValueError("Parameter 'params' must be a list or np.ndarray with at least 2 parameter values")
+        
+        customer_origins_metadata = self.customer_origins.get_metadata()
+        
+        param_gamma, param_lambda = params[0], params[1]
+            
+        if customer_origins_metadata["weighting"][0]["func"] == "logistic":
+            
+            if len(params) < 3:
+                raise ValueError("When using logistic weighting, parameter 'params' must be a list or np.ndarray with at least 3 parameter values")
+        
+            param_gamma, param_lambda, param_lambda2 = params[0], params[1], params[2]
 
         interaction_matrix_df = self.interaction_matrix_df
         
@@ -922,43 +1081,83 @@ class InteractionMatrix:
 
         if customer_origins_metadata["weighting"][0]["func"] in ["power", "exponential"]:
             
-            if len(params) == 2:
+            if len(params) >= 2:
+
                 customer_origins_metadata["weighting"][0]["param"] = float(param_lambda)
+            
             else:
-                raise ValueError ("Huff Model with transport cost weightig of type " + customer_origins_metadata["weighting"][0]["func"] + " must have two input parameters")
+                
+                raise ValueError ("Huff Model with transport cost weighting of type " + customer_origins_metadata["weighting"][0]["func"] + " must have >= 2 input parameters")
         
         elif customer_origins_metadata["weighting"][0]["func"] == "logistic":
             
-            if len(params) == 3:
+            if len(params) >= 3:
+                
                 customer_origins_metadata["weighting"][0]["param"] = [float(param_lambda), float(param_lambda2)]
+            
             else:
-                raise ValueError("Huff Model with transport cost weightig of type " + customer_origins_metadata["weighting"][0]["func"] + " must have three input parameters")
-                        
+
+                raise ValueError("Huff Model with transport cost weightig of type " + customer_origins_metadata["weighting"][0]["func"] + " must have >= 3 input parameters")
+
+        if (customer_origins_metadata["weighting"][0]["func"] in ["power", "exponential"] and len(params) > 2): 
+            
+            for key, param in enumerate(params):
+
+                if key <= 1:
+                    continue
+
+                supply_locations_metadata["weighting"][key-1]["param"] = float(param)
+
+        if (customer_origins_metadata["weighting"][0]["func"] == "logistic" and len(params) > 3):
+
+            for key, param in enumerate(params):
+
+                if key <= 2:
+                    continue
+
+                supply_locations_metadata["weighting"][key-2]["param"] = float(param)
+
         customer_origins.metadata = customer_origins_metadata
-       
+
         p_ij_emp = interaction_matrix_df["p_ij"]
+        E_ij_emp = interaction_matrix_df["E_ij"]         
         
         interaction_matrix_copy = copy.deepcopy(self)
 
         interaction_matrix_copy.utility()
         interaction_matrix_copy.probabilities()
+        interaction_matrix_copy.flows()
 
         interaction_matrix_df_copy = interaction_matrix_copy.get_interaction_matrix_df()
-        p_ij = interaction_matrix_df_copy["p_ij"]
         
-        LL = loglik(
-            observed = p_ij_emp,
+        if fit_by == "flows":            
+                       
+            E_ij = interaction_matrix_df_copy["E_ij"]
+        
+            observed = E_ij_emp
+            expected = E_ij            
+            
+        else:
+        
+            p_ij = interaction_matrix_df_copy["p_ij"]
+            
+            observed = p_ij_emp
             expected = p_ij
-            )
         
+        LL = loglik(
+            observed = observed,
+            expected = expected
+            )        
+       
         return -LL
     
-    def ml_fit(
+    def huff_ml_fit(
         self,
         initial_params: list = [1.0, -2.0],
         method: str = "L-BFGS-B",
         bounds: list = [(0.5, 1), (-3, -1)],        
         constraints: list = [],
+        fit_by = "probabilities",
         update_estimates: bool = True
         ):       
 
@@ -967,41 +1166,59 @@ class InteractionMatrix:
         
         customer_origins = self.customer_origins
         customer_origins_metadata = customer_origins.get_metadata()
+
+        if customer_origins_metadata["weighting"][0]["param"] is None:            
+            params_metadata_customer_origins = 1            
+        else:            
+            if customer_origins_metadata["weighting"][0]["param"] is not None:
+                params_metadata_customer_origins = len(customer_origins_metadata["weighting"][0]["param"])
+            
+        if customer_origins_metadata["weighting"][0]["func"] == "logistic":
+            params_metadata_customer_origins = 2
+        else:
+            params_metadata_customer_origins = 1
+            
+        params_metadata_supply_locations = len(supply_locations_metadata["weighting"])
         
-        if len(initial_params) > 3 or len(initial_params) < 2:
-            raise ValueError("Parameter 'initial_params' must be a list with two or three entries")
+        params_metadata = params_metadata_customer_origins+params_metadata_supply_locations
+
+        if len(initial_params) < 2 or len(initial_params) != params_metadata:
+            raise ValueError("Parameter 'initial_params' must be a list with " + str(params_metadata) + " entries (Attaction: " + str(params_metadata_supply_locations) + ", Transport costs: " + str(params_metadata_customer_origins) + ")")
         
         if len(bounds) != len(initial_params):            
             raise ValueError("Parameter 'bounds' must have the same length as parameter 'initial_params' (" + str(len(bounds)) + ", " + str(len(initial_params)) + ")")
-        
+
         ml_result = minimize(
-            self.huff_loglik,
+            self.loglik,
             initial_params,
+            args=fit_by,
             method = method,
             bounds = bounds,
             constraints = constraints,
             options={'disp': 3}
             )      
 
+        attrac_vars = len(supply_locations_metadata["weighting"])
+
         if ml_result.success:
             
             fitted_params = ml_result.x
             
-            if len(initial_params) == 2:
+            param_gamma = fitted_params[0]
+            supply_locations_metadata["weighting"][0]["param"] = float(param_gamma)
             
-                param_gamma = fitted_params[0]
+            if customer_origins_metadata["weighting"][0]["func"] in ["power", "exponential"]:
+                            
                 param_lambda = fitted_params[1]                
                 param_results = [
                     float(param_gamma), 
                     float(param_lambda)
                     ]
-                
-                supply_locations_metadata["weighting"][0]["param"] = float(param_gamma)
+                                
                 customer_origins_metadata["weighting"][0]["param"] = float(param_lambda)
                 
-            elif len (initial_params) == 3:
+            elif customer_origins_metadata["weighting"][0]["func"] == "logistic":
         
-                param_gamma = fitted_params[0]
                 param_lambda = fitted_params[1]
                 param_lambda2 = fitted_params[2]                
                 param_results = [
@@ -1010,10 +1227,27 @@ class InteractionMatrix:
                     float(param_lambda2)
                     ]
                 
-                supply_locations_metadata["weighting"][0]["param"] = float(param_gamma)
                 customer_origins_metadata["weighting"][0]["param"][0] = float(param_lambda)
-                customer_origins_metadata["weighting"][0]["param"][1] = float(param_lambda2)                          
+                customer_origins_metadata["weighting"][0]["param"][1] = float(param_lambda2)
                 
+            if attrac_vars > 1:
+
+                if customer_origins_metadata["weighting"][0]["func"] == "logistic":
+                    fitted_params_add = 3
+                else:
+                    fitted_params_add = 2 
+
+                for key, var in supply_locations_metadata["weighting"].items():
+
+                    if key > len(supply_locations_metadata["weighting"])-fitted_params_add:
+                        break
+                    
+                    param = float(fitted_params[key+fitted_params_add])
+                    
+                    param_results = param_results + [param]
+
+                    supply_locations_metadata["weighting"][(key+1)]["param"] = float(param)
+                    
             print(f"Optimization via {method} algorithm succeeded with parameters: {', '.join(str(round(par, 3)) for par in param_results)}.")
    
         else:
@@ -1023,13 +1257,14 @@ class InteractionMatrix:
             
             supply_locations_metadata["weighting"][0]["param"] = param_gamma            
             
-            if len(initial_params) == 3:
+            if customer_origins_metadata["weighting"][0]["func"] == "logistic":
                                
                 param_lambda2 = None                
                 customer_origins_metadata["weighting"][0]["param"][0] = param_lambda
                 customer_origins_metadata["weighting"][0]["param"][1] = param_lambda2
             
             else:
+                
                 customer_origins_metadata["weighting"][0]["param"] = param_lambda
                 
             print(f"Optimiziation via {method} algorithm failed with error message: '{ml_result.message}'. See https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html for all available algorithms.")
@@ -1039,14 +1274,25 @@ class InteractionMatrix:
         
         if ml_result.success and update_estimates:
             
+            self.metadata["fit"] = {
+                "function": "huff_ml_fit",
+                "fit_by": fit_by,
+                "initial_params": initial_params,
+                "method": method,
+                "bounds": bounds,
+                "constraints": constraints
+                }
+                
+            
             self.interaction_matrix_df["p_ij_emp"] = self.interaction_matrix_df["p_ij"]
+            self.interaction_matrix_df["E_ij_emp"] = self.interaction_matrix_df["E_ij"]
+            
             self = self.utility()
             self = self.probabilities()
             self = self.flows()            
         
         return self
 
-
     def update(self):
 
         interaction_matrix_df = self.get_interaction_matrix_df()
@@ -1135,6 +1381,49 @@ class InteractionMatrix:
 
         return self
 
+class MarketAreas:
+
+    def __init__(
+        self, 
+        market_areas_df,        
+        metadata
+        ):
+
+        self.market_areas_df = market_areas_df
+        self.metadata = metadata
+   
+    def get_market_areas_df(self):
+        return self.market_areas_df
+    
+    def get_metadata(self):
+        return self.metadata
+    
+    def add_to_model(
+        self,
+        model_object
+        ):
+        
+        if not isinstance(model_object, (HuffModel, MCIModel)):
+            raise ValueError("Parameter 'interaction_matrix' must be of class HuffModel or MCIModel")
+        
+        if isinstance(model_object, MCIModel):
+                        
+            model = MCIModel(
+                interaction_matrix = model_object.interaction_matrix,
+                coefs = model_object.get_coefs_dict(),
+                mci_ols_model = model_object.get_mci_ols_model(),
+                market_areas_df = self.market_areas_df
+                )            
+    
+        if isinstance(model_object, HuffModel):
+            
+            model = HuffModel(
+                interaction_matrix = model_object.interaction_matrix,
+                market_areas_df = self.market_areas_df
+            )
+            
+        return model
+            
 class HuffModel:
 
     def __init__(
@@ -1179,33 +1468,55 @@ class HuffModel:
 
         print("Huff Model")
         print("----------------------------------")
-        print("Supply locations   " + str(supply_locations_metadata["no_points"]))
+        print("Supply locations    " + str(supply_locations_metadata["no_points"]))
         if supply_locations_metadata["attraction_col"][0] is None:
-            print("Attraction column  not defined")
+            print("Attraction column   not defined")
         else:
-            print("Attraction column  " + supply_locations_metadata["attraction_col"][0])
-        print("Customer origins   " + str(customer_origins_metadata["no_points"]))
+            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")
+            print("Market size column  not defined")
         else:
-            print("Market size column " + customer_origins_metadata["marketsize_col"])
+            print("Market size column  " + customer_origins_metadata["marketsize_col"])
         print("----------------------------------")
 
         print("Partial utilities")
-        print("                   Weights")
+        print("                    Weights")
 
         if supply_locations_metadata["weighting"][0]["func"] is None and supply_locations_metadata["weighting"][0]["param"] is None:
-            print("Attraction         not defined")
+            print("Attraction          not defined")
         else:
-            print("Attraction         " + str(round(supply_locations_metadata["weighting"][0]["param"], 3)) + " (" + supply_locations_metadata["weighting"][0]["func"] + ")")
+            print("Attraction          " + str(round(supply_locations_metadata["weighting"][0]["param"], 3)) + " (" + 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("Transport costs    not defined")
+            print("Transport costs     not defined")
         elif customer_origins_metadata["weighting"][0]["func"] in ["power", "exponential"]:
-            print("Transport costs   " + str(round(customer_origins_metadata["weighting"][0]["param"],3)) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")
+            print("Transport costs    " + str(round(customer_origins_metadata["weighting"][0]["param"],3)) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")
         elif customer_origins_metadata["weighting"][0]["func"] == "logistic":
-            print("Transport costs   " + str(round(customer_origins_metadata["weighting"][0]["param"][0],3)) + ", " + str(round(customer_origins_metadata["weighting"][0]["param"][1],3)) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")
+            print("Transport costs    " + str(round(customer_origins_metadata["weighting"][0]["param"][0],3)) + ", " + str(round(customer_origins_metadata["weighting"][0]["param"][1],3)) + " (" + customer_origins_metadata["weighting"][0]["func"] + ")")
+
+        attrac_vars = supply_locations_metadata["attraction_col"]
+        attrac_vars_no = len(attrac_vars)
+        
+        if attrac_vars_no > 1:
+                        
+            for key, attrac_var in enumerate(attrac_vars):
+                
+                if key == 0:
+                    continue
+                
+                if key not in supply_locations_metadata["weighting"].keys():
+                    
+                    print(f"{attrac_vars[key][:16]:16}    not defined")
+                    
+                else:
 
+                    name = supply_locations_metadata["weighting"][key]["name"]
+                    param = supply_locations_metadata["weighting"][key]["param"]
+                    func = supply_locations_metadata["weighting"][key]["func"]
+
+                    print(f"{name[:16]:16}    {round(param, 3)} ({func})")
+                    
         print("----------------------------------")
         
         huff_modelfit = self.modelfit()
@@ -1219,7 +1530,11 @@ class HuffModel:
             print("Mean squared error             ", round(huff_modelfit[1]["MSE"], 2))
             print("Root mean squared error        ", round(huff_modelfit[1]["RMSE"], 2))
             print("Mean absolute error            ", round(huff_modelfit[1]["MAE"], 2))
-            print("Mean absolute percentage error ", round(huff_modelfit[1]["MAPE"], 2))
+            if huff_modelfit[1]["MAPE"] is not None:
+                print("Mean absolute percentage error ", round(huff_modelfit[1]["MAPE"], 2))
+            else:
+                print("Mean absolute percentage error  Not calculated")
+            print("Symmetric MAPE                 ", round(huff_modelfit[1]["sMAPE"], 2))
             print("Absolute percentage errors")
             
             APE_list = [
@@ -1302,6 +1617,15 @@ class HuffModel:
 
         customer_origins.metadata = customer_origins_metadata
         supply_locations.metadata = supply_locations_metadata
+        
+        interaction_matrix_metadata = {
+            "fit": {
+                "function": "mci_fit",
+                "fit_by": "probabilities",
+                "method": "OLS"
+                }
+            }
+        
         interaction_matrix = InteractionMatrix(
             interaction_matrix_df,
             customer_origins,
@@ -1326,18 +1650,21 @@ class HuffModel:
         
         return self
     
-    def modelfit(self):
+    def modelfit(
+        self,
+        by = "p_ij"
+        ):
         
         interaction_matrix = self.interaction_matrix        
         interaction_matrix_df = interaction_matrix.get_interaction_matrix_df()
         
-        if ("p_ij" in interaction_matrix_df.columns and "p_ij_emp" in interaction_matrix_df.columns):
+        if (by in interaction_matrix_df.columns and by+"_emp" in interaction_matrix_df.columns):
             
             try:
             
                 huff_modelfit = modelfit(
-                    interaction_matrix_df["p_ij_emp"],
-                    interaction_matrix_df["p_ij"]
+                    interaction_matrix_df[by+"_emp"],
+                    interaction_matrix_df[by]
                 )
                 
                 return huff_modelfit
@@ -1472,7 +1799,11 @@ class MCIModel:
             print("Mean squared error             ", round(mci_modelfit[1]["MSE"], 2))
             print("Root mean squared error        ", round(mci_modelfit[1]["RMSE"], 2))
             print("Mean absolute error            ", round(mci_modelfit[1]["MAE"], 2))
-            print("Mean absolute percentage error ", round(mci_modelfit[1]["MAPE"], 2))
+            if mci_modelfit[1]["MAPE"] is not None:
+                print("Mean absolute percentage error ", round(mci_modelfit[1]["MAPE"], 2))
+            else:
+                print("Mean absolute percentage error  Not calculated")
+            print("Symmetric MAPE                 ", round(mci_modelfit[1]["sMAPE"], 2))
             
             print("Absolute percentage errors")
             APE_list = [
@@ -1720,6 +2051,7 @@ def load_geodata (
         "marketsize_col": None,
         "weighting": {
             0: {
+                "name": None,
                 "func": None, 
                 "param": None
                 }
@@ -1727,7 +2059,7 @@ def load_geodata (
         "crs_input": crs_input,
         "crs_output": crs_output,
         "no_points": len(geodata_gpd)
-        }    
+        }
     
     if location_type == "origins":
 
@@ -1848,8 +2180,10 @@ def load_interaction_matrix(
     csv_sep = ";", 
     csv_decimal = ",", 
     csv_encoding="unicode_escape",
+    xlsx_sheet: str = None,
     crs_input = "EPSG:4326",
-    crs_output = "EPSG:4326"
+    crs_output = "EPSG:4326",
+    check_df_vars = True
     ):    
 
     if isinstance(data, pd.DataFrame):
@@ -1865,7 +2199,13 @@ def load_interaction_matrix(
                 encoding = csv_encoding
                 )    
         elif data_type == "xlsx":
-            interaction_matrix_df = pd.read_excel(data)
+            if xlsx_sheet is not None:
+                interaction_matrix_df = pd.read_excel(
+                    data, 
+                    sheet_name=xlsx_sheet
+                    )
+            else:
+                interaction_matrix_df = pd.read_excel(data)
         else:
             raise TypeError("Unknown type of data")
     else:
@@ -1884,10 +2224,11 @@ def load_interaction_matrix(
     if market_size_col is not None:
         cols_check = cols_check + [market_size_col]
 
-    check_vars(
-        interaction_matrix_df,
-        cols = cols_check
-        )
+    if check_df_vars:
+        check_vars(
+            interaction_matrix_df,
+            cols = cols_check
+            )
 
     if customer_origins_coords_col is not None:
 
@@ -1942,6 +2283,7 @@ def load_interaction_matrix(
         "marketsize_col": market_size_col,
         "weighting": {
             0: {
+                "name": None,
                 "func": None, 
                 "param": None
                 }
@@ -2009,6 +2351,7 @@ def load_interaction_matrix(
         "marketsize_col": None,
         "weighting": {
             0: {
+                "name": None,
                 "func": None, 
                 "param": None
                 }
@@ -2056,7 +2399,12 @@ def load_interaction_matrix(
             }
             )
     
-    metadata = {}
+    metadata = {
+        "fit": {
+            "function": None,
+            "fit_by": None
+        }
+    }
 
     interaction_matrix = InteractionMatrix(
         interaction_matrix_df=interaction_matrix_df,
@@ -2067,6 +2415,74 @@ def load_interaction_matrix(
     
     return interaction_matrix
 
+def load_marketareas(
+    data,
+    supply_locations_col: str,
+    total_col: str,  
+    data_type = "csv", 
+    csv_sep = ";", 
+    csv_decimal = ",", 
+    csv_encoding="unicode_escape",
+    xlsx_sheet: str = None,
+    check_df_vars = True
+    ):    
+
+    if isinstance(data, pd.DataFrame):
+        market_areas_df = data
+    elif isinstance(data, str):
+        if data_type not in ["csv", "xlsx"]:
+            raise ValueError ("data_type must be 'csv' or 'xlsx'")
+        if data_type == "csv":
+            market_areas_df = pd.read_csv(
+                data, 
+                sep = csv_sep, 
+                decimal = csv_decimal, 
+                encoding = csv_encoding
+                )    
+        elif data_type == "xlsx":            
+            if xlsx_sheet is not None:
+                market_areas_df = pd.read_excel(
+                    data, 
+                    sheet_name=xlsx_sheet
+                    )
+            else:
+                market_areas_df = pd.read_excel(data)
+        else:
+            raise TypeError("Unknown type of data")
+    else:
+        raise TypeError("data must be pandas.DataFrame or file (.csv, .xlsx)")
+    
+    if supply_locations_col not in market_areas_df.columns:
+        raise KeyError ("Column " + supply_locations_col + " not in data")
+    if total_col not in market_areas_df.columns:
+        raise KeyError ("Column " + supply_locations_col + " not in data")
+    
+    if check_df_vars:
+        check_vars(
+            market_areas_df,
+            cols = [total_col]
+            )
+    
+    market_areas_df = market_areas_df.rename(
+        columns = {
+            supply_locations_col: "j",
+            total_col: "T_j"
+        }
+        )
+    
+    metadata = {
+        "unique_id": supply_locations_col,
+        "total_col": total_col,
+        "no_points": len(market_areas_df)
+        }
+    
+    market_areas = MarketAreas(
+        market_areas_df,
+        metadata
+        )
+    
+    return market_areas  
+
 def market_shares(
     df: pd.DataFrame,
     turnover_col: str,
@@ -2291,7 +2707,15 @@ def modelfit(
     residuals_sq = residuals**2
     residuals_abs = abs(residuals)
  
-    APE = abs(observed-expected)/observed*100
+    if any(observed == 0):
+        print ("Vector 'observed' contains values equal to zero. No APE/MAPE calculated.")
+        APE = np.full_like(observed, np.nan)
+        MAPE = None
+    else:
+        APE = abs(observed-expected)/observed*100
+        MAPE = float(np.mean(APE))
+        
+    sAPE = abs(observed-expected)/((abs(observed)+abs(expected))/2)*100
     
     data_residuals = pd.DataFrame({
         "observed": observed,
@@ -2299,7 +2723,8 @@ def modelfit(
         "residuals": residuals,
         "residuals_sq": residuals_sq,
         "residuals_abs": residuals_abs,
-        "APE": APE
+        "APE": APE,
+        "sAPE": sAPE
         })
 
     SQR = float(np.sum(residuals_sq))
@@ -2310,7 +2735,8 @@ def modelfit(
     MSE = float(SQR/observed_no)
     RMSE = float(sqrt(MSE))
     MAE = float(SAR/observed_no)
-    MAPE = float(np.mean(APE))
+    
+    sMAPE = float(np.mean(sAPE))
 
     resid_below5 = float(len(data_residuals[data_residuals["APE"] < 5])/expected_no*100)
     resid_below10 = float(len(data_residuals[data_residuals["APE"] < 10])/expected_no*100)
@@ -2332,6 +2758,7 @@ def modelfit(
         "RMSE": RMSE,
         "MAE": MAE,
         "MAPE": MAPE,
+        "sMAPE": sMAPE,
         "APE": {
             "resid_below5": resid_below5,
             "resid_below10": resid_below10,
@@ -2362,7 +2789,7 @@ def loglik(
             observed, 
             expected
             )    
-        residuals_sq = model_fit[0]["residuals_sq"]
+        residuals_sq = model_fit[0]["residuals_sq"]        
         
         LL = np.sum(np.log(residuals_sq))
 

huff/tests/tests_huff.py

@@ -4,13 +4,13 @@
 # Author:      Thomas Wieland 
 #              ORCID: 0000-0001-5168-9846
 #              mail: geowieland@googlemail.com              
-# Version:     1.4.1
-# Last update: 2025-06-16 17:43
+# Version:     1.5.0
+# Last update: 2025-06-25 18:32
 # Copyright (c) 2025 Thomas Wieland
 #-----------------------------------------------------------------------
 
 
-from huff.models import create_interaction_matrix, get_isochrones, load_geodata, load_interaction_matrix, market_shares, modelfit
+from huff.models import create_interaction_matrix, get_isochrones, load_geodata, load_interaction_matrix, load_marketareas, market_shares, modelfit
 from huff.osm import map_with_basemap
 from huff.gistools import buffers, point_spatial_join
 
@@ -101,8 +101,8 @@ haslach_interactionmatrix = create_interaction_matrix(
 # Creating interaction matrix
 
 haslach_interactionmatrix.transport_costs(
-    ors_auth="5b3ce3597851110001cf62480a15aafdb5a64f4d91805929f8af6abd"
-    #network=False,
+    #ors_auth="5b3ce3597851110001cf62480a15aafdb5a64f4d91805929f8af6abd"
+    network=False,
     #distance_unit="meters",
     # set network = True to calculate transport costs matrix via ORS API (default)
     )
@@ -131,7 +131,7 @@ print(huff_model.get_market_areas_df())
 
 # Maximum Likelihood fit for Huff Model:
 
-haslach_interactionmatrix.ml_fit(
+haslach_interactionmatrix.huff_ml_fit(
     #initial_params=[1, -2],
     initial_params=[1, 9, -0.6],
     method="trust-constr",
@@ -212,8 +212,10 @@ Wieland2015_interaction_matrix = load_interaction_matrix(
         "K", 
         "K_KKr"
         ],
+    market_size_col="Sum_Ek1",
+    flows_col="Anb_Eink1",
     transport_costs_col="Dist_Min2",
-    probabilities_col="MA",
+    probabilities_col="MA_Anb1",
     data_type="xlsx"
     )
 
@@ -240,6 +242,93 @@ Wieland2015_fit.summary()
 # MCI model summary
 
 
+# Parameter estimation via Maximum Likelihood:
+
+Wieland2015_interaction_matrix2 = load_interaction_matrix(
+    data="data/Wieland2015.xlsx",
+    customer_origins_col="Quellort",
+    supply_locations_col="Zielort",
+    attraction_col=[
+        "VF", 
+        "K", 
+        "K_KKr"
+        ],
+    market_size_col="Sum_Ek",
+    flows_col="Anb_Eink",
+    transport_costs_col="Dist_Min2",
+    probabilities_col="MA_Anb",
+    data_type="xlsx",
+    xlsx_sheet="interactionmatrix",
+    check_df_vars=False
+    )
+# Loading empirical interaction matrix again
+
+Wieland2015_interaction_matrix2.define_weightings(
+    vars_funcs = {
+            0: {
+                "name": "A_j",
+                "func": "power"
+            },
+            1: {
+                "name": "t_ij",
+                "func": "power",
+                #"func": "exponential"
+                #"func": "logistic"                
+            },
+            2: {
+                "name": "K",
+                "func": "power"
+            },
+            3: {
+                "name": "K_KKr",
+                "func": "power"
+            }
+            }
+    )
+# Defining weighting functions
+
+Wieland2015_interaction_matrix2.huff_ml_fit(
+    # Power TC function
+    initial_params=[0.9, -0.5, 0.5, 0.3],
+    bounds=[(0.5, 1), (-0.7, -0.2), (0.2, 0.7), (0.2, 0.7)],
+    # # Logistic TC function:
+    # initial_params=[0.9, 10, -0.5, 0.5, 0.3],
+    # bounds=[(0.5, 1), (8, 12), (-0.7, -0.2), (0.2, 0.7), (0.2, 0.7)],
+    fit_by="flows",
+    method = "trust-constr"
+)
+# ML fit with power transport cost function
+
+Wieland2015_interaction_matrix2.summary()
+# Summary of interaction matrix
+
+huff_model_fit2 = Wieland2015_interaction_matrix2.marketareas()
+# Calculation of market areas
+
+huff_model_fit2.summary()
+# Summary of Hudd model
+
+
+# Loading and including total market areas
+
+Wieland2025_totalmarketareas = load_marketareas(
+    data="data/Wieland2015.xlsx",
+    supply_locations_col="Zielort",
+    total_col="Anb_Eink",
+    data_type="xlsx",
+    xlsx_sheet="total_marketareas"
+)
+# Loading empirical total market areas
+
+huff_model_fit2 = Wieland2025_totalmarketareas.add_to_model(
+    huff_model_fit2
+    )
+# Adding total market areas to HuffModel object
+
+print(huff_model_fit2.get_market_areas_df())
+# Showing total market areas of HuffModel object
+
+
 # Buffer analysis:
 
 Haslach_supermarkets_gdf = Haslach_supermarkets.get_geodata_gpd_original()
@@ -298,7 +387,8 @@ map_with_basemap(
         Haslach_supermarkets_gdf
         ],
     styles={
-        0: {"name": "Isochrones",
+        0: {
+            "name": "Isochrones",
             "color": {
                 "segm_min": {
                     "3": "midnightblue", 
@@ -310,11 +400,13 @@ map_with_basemap(
                 },
             "alpha": 0.3
         },
-        1: {"name": "Districts",
+        1: {
+            "name": "Districts",
             "color": "black",
             "alpha": 1
         },
-        2: {"name": "Supermarket chains",
+        2: {
+            "name": "Supermarket chains",
             "color": {
                 "Name": {
                     "Aldi S├╝d": "blue",

{huff-1.4.1.dist-info → huff-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: huff
-Version: 1.4.1
+Version: 1.5.0
 Summary: huff: Huff Model Market Area Analysis
 Author: Thomas Wieland
 Author-email: geowieland@googlemail.com
@@ -28,14 +28,25 @@ Thomas Wieland [ORCID](https://orcid.org/0000-0001-5168-9846) [EMail](mailto:geo
 See the /tests directory for usage examples of most of the included functions.
 
 
+## Updates v1.5.0
+- Extensions:
+  - Huff model utility via InteractionMatrix.utility() extended to >2 variables
+  - Huff Model Maximum Likelihood fit via InteractionMatrix.huff_ml_fit() extended: >2 variables, fit by flows or probabilities
+  - Loading total market areas data as class MarketAreas
+  - Extended output of InteractionMatrix.summary()
+- Bugfixes:
+  - InteractionMatrix.utility(): Tests for availability of relevant columns
+  - InteractionMatrix.flows(): Tests for availability of relevant columns
+  - modelfit(): Symmetrical (M)APE instead of (M)APE when observed contains zeros
+
 ## Features
 
 - **Huff Model**: 
   - Defining origins and destinations with weightings
   - Creating interaction matrix from origins and destinations
-  - Market simulation with basic Huff Model
   - Different function types: power, exponential, logistic
-  - Huff model parameter estimation via Maximum Likelihood (ML)
+  - Huff model parameter estimation via Maximum Likelihood (ML) by probalities and customer flows
+  - Huff model market simulation
 - **Multiplicative Competitive Interaction Model**: 
   - Log-centering transformation of interaction matrix
   - Fitting MCI model with >= 2 independent variables

{huff-1.4.1.dist-info → huff-1.5.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 huff/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 huff/gistools.py,sha256=fgeE1IsUO7UIaawb23kuiz_Rlxn7T18iLLTA5yvgp74,7038
-huff/models.py,sha256=3IxZLUp8-sC-sy0qJ677-cYEi09cqNOuOw_QBvr-K5s,89975
+huff/models.py,sha256=fGQP6eZOkV9wRVNw_0jYY8zIW74VAR0MMQ9YR8Vjcn4,105491
 huff/ors.py,sha256=JlO2UEishQX87PIiktksOrVT5QdB-GEWgjXcxoR_KuA,11929
 huff/osm.py,sha256=9A-7hxeZyjA2r8w2_IqqwH14qq2Y9AS1GxVKOD7utqs,7747
 huff/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-huff/tests/tests_huff.py,sha256=nnOcZmhvEQMsnCf7YKnm-2vAY_h7FA7p7E2UPBDXLRU,9435
+huff/tests/tests_huff.py,sha256=xhJcUYQ6dJIg6cPMez8yRIcicvuXkww8NPHXmt-Qrjg,11955
 huff/tests/data/Haslach.cpg,sha256=OtMDH1UDpEBK-CUmLugjLMBNTqZoPULF3QovKiesmCQ,5
 huff/tests/data/Haslach.dbf,sha256=GVPIt05OzDO7UrRDcsMhiYWvyXAPg6Z-qkiysFzj-fc,506
 huff/tests/data/Haslach.prj,sha256=2Jy1Vlzh7UxQ1MXpZ9UYLs2SxfrObj2xkEkZyLqmGTY,437
@@ -23,8 +23,8 @@ huff/tests/data/Haslach_supermarkets.prj,sha256=2Jy1Vlzh7UxQ1MXpZ9UYLs2SxfrObj2x
 huff/tests/data/Haslach_supermarkets.qmd,sha256=JlcOYzG4vI1NH1IuOpxwIPnJsCyC-pDRAI00TzEvNf0,2522
 huff/tests/data/Haslach_supermarkets.shp,sha256=X7QbQ0BTMag_B-bDRbpr-go2BQIXo3Y8zMAKpYZmlps,324
 huff/tests/data/Haslach_supermarkets.shx,sha256=j23QHX-SmdAeN04rw0x8nUOran-OCg_T6r_LvzzEPWs,164
-huff/tests/data/Wieland2015.xlsx,sha256=SaVM-Hi5dBTmf2bzszMnZ2Ec8NUE05S_5F2lQj0ayS0,19641
-huff-1.4.1.dist-info/METADATA,sha256=TMOldW_srTquKEghHkuMKyofG2MjUMUV4OKfdNUyFoU,5692
-huff-1.4.1.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-huff-1.4.1.dist-info/top_level.txt,sha256=nlzX-PxZNFmIxANIJMySuIFPihd6qOBkRlhIC28NEsQ,5
-huff-1.4.1.dist-info/RECORD,,
+huff/tests/data/Wieland2015.xlsx,sha256=jUt9YcRrYL99AjxzXKMXD3o5erjd9r_jYfnALdrTQ3o,24333
+huff-1.5.0.dist-info/METADATA,sha256=Ig_hu8ssyzbtuAUUxMw3ykAHpthSoyMeSxAgeSw3P9o,6319
+huff-1.5.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+huff-1.5.0.dist-info/top_level.txt,sha256=nlzX-PxZNFmIxANIJMySuIFPihd6qOBkRlhIC28NEsQ,5
+huff-1.5.0.dist-info/RECORD,,