Huff Model (Business Analyst)

Available with Business Analyst license.

Summary

Creates a probability surface to predict the sales potential of an area based on distance and an attractiveness factor.

Usage

  • The Input Facility Features parameter layer is a point layer that represents competitors or existing stores.

  • The Input Candidate Features parameter layer is a point layer that represents the potential stores layer to evaluate.

  • The Huff Model tool takes into account all of the locations in the Input Facility Features parameter layer but only a single feature in the Input Candidate Features parameter layer in an analysis. You can limit the locations in an analysis by selecting either the Input Facility Features or Input Candidate Features parameter layer.

  • The attractiveness value used for the analysis must be the same field in the Input Facility Features and Input Candidate Features parameters.

  • The Input Sales Potential Features parameter layer can be a point layer or a polygon layer that has a numeric field representing sales potential. It can be based on disposable income or population, for example, or any other variable.

  • The Enrich Layer tool can be used to derive the Input Sales Potential Features parameter layer.

  • Geodesic distance is used for distance calculations.

Syntax

arcpy.ba.HuffModel(in_facility_features, facility_id_field, in_candidate_features, candidate_id_field, in_sales_potential_features, sales_potential_id_field, sales_potential_field, out_feature_class, attractiveness_variables, distance_exponent, {distance_type}, {distance_units}, {out_distance_matrix}, {travel_direction}, {time_of_day}, {time_zone})
ParameterExplanationData Type
in_facility_features

An input point feature layer representing existing facility locations. It is the first feature from the layer, or the feature selected when a selection is available.

Feature Layer
facility_id_field

A unique ID field for existing facilities.

Field
in_candidate_features

An input point feature layer representing new candidate facility locations. It is the first feature from the layer or the feature selected when a selection is available.

Feature Layer
candidate_id_field

A unique ID field for candidate facilities.

Field
in_sales_potential_features

An input point or polygon feature layer used to calculate the sales potential. It is either all features from a layer or only selected features when a selection is available.

Feature Layer
sales_potential_id_field

A unique ID field for sales potential features.

Field
sales_potential_field

The field containing the values that will be used to calculate the sales potential.

Field
out_feature_class

The output feature class that will contain the tool results, representing the probability of sales.

Feature Class
attractiveness_variables
[[existing_facilities_value, candidates_location_value, exponent],...]

The attribute fields that indicate the attractiveness of each competitor. In many cases, the size of the facility is used as a substitute for attractiveness and will be a multivalue table.

An additional attractiveness variable is needed. The attractiveness field must be present in the existing facilities (competitors) and the candidate facilities layer.

  • existing_facilities_value—Numeric field in the in_facility_features parameter layer that represents attractiveness.
  • candidates_location_value—Numeric field in the in_candidate_features parameter layer that matches the attractiveness value from the in_facility_features parameter layer. Distance does not require a matching field.
  • exponent—The value that determines how much of a factor the variable is to the attractiveness value. The default value is 1.
Value Table
distance_exponent

The distance exponent is generally a negative number because attractiveness decreases when distance increases. The default value is -1.5.

Double
distance_type
(Optional)

The type of distance, based on method of travel, that will be used. The default value is Straight Line.

String
distance_units
(Optional)

The distance-measuring units to be used when calculating distance.

String
out_distance_matrix
(Optional)

The name and location of the matrix table of distance calculations. The IDs for the Input Facilitates Features and Input Candidate Features parameters must be unique.

Table
travel_direction
(Optional)

Specifies the direction of travel that will be used between stores and sales potential features.

  • TOWARD_STORESThe direction of travel will be from sales potential features to stores. This is the default.
  • AWAY_FROM_STORESThe direction of travel will be from stores to sales potential features.
String
time_of_day
(Optional)

The time and date that will be used when calculating distance.

Date
time_zone
(Optional)

Specifies the time zone that will be used for the Time of Day parameter.

  • TIME_ZONE_AT_LOCATIONThe time zone in which the territories are located will be used. This is the default.
  • UTCCoordinated universal time (UTC) will be used.
String

Derived Output

NameExplanationData Type
out_predicted_sales

The output model.

Double

Code sample

HuffModel example (Python window)

The following Python window script demonstrates how to use the HuffModel function.

import arcpy
arcpy.ba.HuffModel("starbucks_layer", "IDField", "potential_store_layer", "IDField", "HuffModelTestData.gdb\CT", "IDField", "TOTPOP_CY", "Starbucks_HuffModel", "SALES # 1", -1.5, "STRAIGHT_LINE_DISTANCE", "MILES", None, "TOWARD_STORES", None, "TIME_ZONE_AT_LOCATION")

Licensing information

  • Basic: Requires Business Analyst
  • Standard: Requires Business Analyst
  • Advanced: Requires Business Analyst

Related topics