Distance Decay Report—Help

Available with Business Analyst license.

Summary
Usage
Syntax
Code sample
Environments
Licensing information

Summary

Calculates market penetration for a number of ring or drive-time polygons around your stores.

Usage

When determining the Total Market Counts Calculation Method, the Calculate Using Geography Level option will allow you to choose from any polygon layer that has been set up using the Analysis Layer Setup utility.
The Total Market Counts Field parameter is available if the option In the layer attribute table is selected in the Total Market Counts Calculation Method parameter.
In principle, distance decay trade areas are not different from a simple weighted area. Business Analyst distance decay functionality provides the mechanism to create these areas based on the geographic principle of distance decay: the propensity to visit a store decreases as the distance to the store increases.
Distance decay area calculates market penetration values for a number of ring or drive-time polygons around your stores.
The Distance Decay Report shows you how far your customers are traveling to a store in comparison to a base value, such as population.
You must have store and customer layers with customer assignments already generated.

Syntax

DistanceDecayReport_ba (InputFeatureLayer, IDField, All_Or_Single_Or_Selected, RingsType, RingsCollection, {MeasureUnits}, CustomerLayer, MarketPenetrationTMCType, ReportTitle, MarketPenetrationReportDirectory, {ByID_Or_ByName}, {Single_Site}, {Donut}, {RemoveOverlap}, {BorderShape}, IN_MP_STORE_ID, {UseSelectedCustomers}, {CustomerWeightField}, {IN_CL_STORE_ID}, MarketPenetrationTMCField, InputGeographyLevel, MarketPenetrationTMCSummarization, {ReportFormats}, {CreateReport}, {BarrierFeatureClasses})

Parameter	Explanation	Data Type
InputFeatureLayer	The input feature class containing center points for the report. In most cases, this will be a Business Analyst store layer.	Feature Layer
IDField	Unique ID field in the store layer.	Field
All_Or_Single_Or_Selected	Creates trade areas for points in the input feature layer. ALL —Trade areas are created for all points. SINGLE —Trade areas are created for a single point. SELECTED —Trade areas are created for selected points in ArcMap.	String
RingsType	Determines how the generated trade areas will be derived. Simple Ring Areas —Generates one or more static rings based on the center point(s) of the store layer. Drive Time Areas —Generates one or more drive-time polygons based on the center point(s) of the store layer.	String
RingsCollection [RingsCollection,...]	The distances, in ascending size, used to create trade areas around the input features.	Double
MeasureUnits (Optional)	The units used with the distance values. By default, the units defined in the Business Analyst preferences will be selected. Decimal Degrees Feet Kilometers Meters Miles —This is the default. Nautical Miles Yards	String
CustomerLayer	The input feature class containing the points for the customer distribution. In most cases, this will be a Business Analyst customer layer.	Feature Layer
MarketPenetrationTMCType	Determines the location where the market count calculation will be derived. In the layer attribute table —Calculates the market penetration based on nonstandard geography. Calculate using Geography Level —Calculates the market penetration based on a standard geography layer. Calculate Using Business Analyst Online Data —Calculates the market penetration based on online Business Analyst data.	String
ReportTitle	The title for the report.	String
MarketPenetrationReportDirectory	The output directory where the report will be saved.	Folder
ByID_Or_ByName (Optional)	Field used to select a single point. ID —Selects a single point using the store ID field. Name —Selects a single point using the store name field.	String
Single_Site (Optional)	ID or name of store to be used as the single point.	String
Donut (Optional)	Creates nonoverlapping concentric rings or donut bands. True —Concentric rings are created. This is the default option. False —Creates output polygons that are donut rings. For example, if three radii (1, 2, and 3 miles) are entered, three output bands would be created with 0–1-, 1–3-, and 3–5-mile rings.	Boolean
RemoveOverlap (Optional)	Removes the overlap using the Thiessen approach by drawing lines of equal distance between two adjacent polygons. True —Removes the overlap between trade areas. False —Does not remove the overlap between trade areas. This is the default.	Boolean
BorderShape (Optional)	Creates a detailed border ignoring areas that cannot be reached when driven. True —Generates detailed borders around trade areas. False —Does not generate detailed borders around trade areas. This is the default.	Boolean
IN_MP_STORE_ID	Unique ID field based on the layer for calculating market penetration. This store ID is a field in the Market Penetration layer.	Field
UseSelectedCustomers (Optional)	Uses selected features to generate the Distance Decay report. True —Generates the Distance Decay report on selected features. False —Generates the Distance Decay report on all features. This is the default	Boolean
CustomerWeightField (Optional)	Defines the attribute of the customer layer that will be used to weight the trade areas.	Field
IN_CL_STORE_ID (Optional)	The store ID field that will be used to identify which customers are associated with each store. This Store ID is a field in the Customer Layer.	Field
MarketPenetrationTMCField	The field that contains the base total market counts from the market penetration layer used in calculating the market penetration.	String
InputGeographyLevel	Selects the geography level that will contain the total market counts.	Feature Layer
MarketPenetrationTMCSummarization	The attribute field that contains the variable used for the total market count selected from the geography level.	String
ReportFormats [ReportFormats,...] (Optional)	Select the desired report output format. Simple XML PDF HTML CSV ZIP XLSX Stripped XLSX	String
CreateReport (Optional)	Generates a report. True —Will generate a Summarize Points report. This is the default. False —Will not generate a Summarize Points report.	Boolean
BarrierFeatureClasses [BarrierFeatureClasses,...] (Optional)	Point, line, or polygon barriers to use when drive time or drive distance is used to calculate distances.	Feature Layer

Code sample

DistanceDecayReport example (stand-alone script)

# Name: DistanceDecayReport.py
# Description: Calculates the market penetration in San Francisco based on a series of simple ring trade areas comparing the sales in each ring to the total population.
# Author: Esri

# Import system modules
import arcview
import arcpy

arcpy.ImportToolbox(r"C:\Program Files (x86)\ArcGIS\Desktop10.7\Business Analyst\ArcToolbox\Toolboxes\Business Analyst Tools.tbx")
 
try:
# Acquire extension license 
  arcpy.CheckOutExtension("Business")
     
# Define input and output parameters for the Distance Decay Report tool
  Store = "C:/temp/sf_stores.shp"
  Cust = "C:/temp/sf_cust.shp"
  Id = "STORE_ID"
  MarketPen = "C:/Temp/Decay/MpLayer.shp"
  Method = "Calculate using Geography Level"
  Weight = "SALES"
  Data = "C:/ArcGIS/Business Analyst/US_2018/Data/Demographic Data/BlockGroups_bg.bds"
  Var = "TOTPOP_CY"
  Output = "C:/temp/DecayReport2"
 
# Create Distance Decay reports
  arcpy.DistanceDecayReport_ba(Store, Id, "ALL", 'Simple Ring Areas', "1;2;3", "Miles", Cust, Method, Weight, Data, Var, "Ring Penetration", Output, "#", "#", "false", "false","false", "#", "false", "#", "#",sMarketPen)
 
# Release extension license 
  arcpy.CheckInExtension("Business")
 
except:
  print arcpy.GetMessages(2)

Environments

This tool does not use any geoprocessing environments.

Licensing information

ArcGIS Desktop Basic: Requires Business Analyst
ArcGIS Desktop Standard: Requires Business Analyst
ArcGIS Desktop Advanced: Requires Business Analyst