Calculate Distance Band from Neighbor Count (Spatial Statistics)

Summary

Returns the minimum, the maximum, and the average distance to the specified Nth nearest neighbor (N is an input parameter) for a set of features. Results are written as tool execution messages.

Illustration

Usage

• Given a set of features, this tool returns three numbers: the minimum, the maximum, and the average distance to a specified number of neighbors (N). Example: if you specify 8 for the Neighbors parameter, this tool creates a list of distances between every feature and its 8th nearest neighbor; from this list of distances it then calculates the minimum, maximum, and average distance.

  • The maximum value is the distance you would have to travel away from each feature to ensure every feature has at least N neighbors.
  • The minimum value is the distance you would travel away from each feature to ensure that at least one feature has N neighbors.
  • The average value is the average distance you would travel away from each feature to find its N nearest neighbors.

• The Calculate Distance Band from Neighbor Count tool returns three values: Minimum, Average, and Maximum N neighbor distance. The values are written as messages at the bottom of the Geoprocessing pane during tool execution and are passed as derived output values for potential use in models or scripts. You may access the messages by hovering over the progress bar, clicking on the pop-out button, or expanding the messages section in the Geoprocessing pane. You may also access the messages for a previously run tool via the Geoprocessing History.

• Some tools, such as Hot Spot Analysis (Getis-Ord Gi*) and Spatial Autocorrelation (Global Moran's I), allow you to specify a neighborhood Distance Band or Threshold Distance value. By using the Maximum Distance output value from this tool for the Distance Band or Threshold Distance parameter, you ensure every feature in the input feature class has at least N neighbors.

• This tool provides one strategy for determining a Distance Band or Threshold Distance value to use with tools in the Spatial Statistics Toolbox such as Hot Spot Analysis (Getis-Ord Gi*) or Cluster and Outlier Analysis (Local Moran's I). See Selecting a Fixed Distance for additional strategies.

• The distances returned by this tool are in the units of the geoprocessing environment Output Coordinate System.

• When the Input Feature Class is not projected (that is, when coordinates are given in degrees, minutes, and seconds) or when the output coordinate system is set to a Geographic Coordinate System, distances are computed using chordal measurements. Chordal distance measurements are used because they can be computed quickly and provide very good estimates of true geodesic distances, at least for points within about thirty degrees of each other. Chordal distances are based on an oblate spheroid. Given any two points on the earth's surface, the chordal distance between them is the length of a line, passing through the three-dimensional earth, to connect those two points. Chordal distances are reported in meters.

  Caution:

  Be sure to project your data if your study area extends beyond 30 degrees. Chordal distances are not a good estimate of geodesic distances beyond 30 degrees.

• For line and polygon features, feature centroids are used in distance computations. For multipoints, polylines, or polygons with multiple parts, the centroid is computed using the weighted mean center of all feature parts. The weighting for point features is 1, for line features is length, and for polygon features is area.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The feature class or layer used to calculate distance statistics.	Feature Layer
Neighbors	The number of neighbors (N) to consider for each feature. This number should be any integer between one and the total number of features in the feature class. A list of distances between each feature and its Nth neighbor is compiled, and the maximum, minimum, and average distances are output to the Results window.	Long
Distance Method	Specifies how distances are calculated from each feature to neighboring features. Euclidean—The straight-line distance between two points (as the crow flies) Manhattan—The distance between two points measured along axes at right angles (city block); calculated by summing the (absolute) difference between the x- and y-coordinates	String

Derived Output

Label	Explanation	Data Type
Minimum Distance	The minimum N neighbor distance.	Double
Average Distance	The average N neighbor distance.	Double
Maximum Distance	The maximum N neighbor distance.	Double

Python

arcpy.stats.CalculateDistanceBand(Input_Features, Neighbors, Distance_Method)

Name	Explanation	Data Type
Input_Features	The feature class or layer used to calculate distance statistics.	Feature Layer
Neighbors	The number of neighbors (N) to consider for each feature. This number should be any integer between one and the total number of features in the feature class. A list of distances between each feature and its Nth neighbor is compiled, and the maximum, minimum, and average distances are output to the Results window.	Long
Distance_Method	Specifies how distances are calculated from each feature to neighboring features. EUCLIDEAN_DISTANCE—The straight-line distance between two points (as the crow flies) MANHATTAN_DISTANCE—The distance between two points measured along axes at right angles (city block); calculated by summing the (absolute) difference between the x- and y-coordinates	String

Derived Output

Name	Explanation	Data Type
Minimum_Distance	The minimum N neighbor distance.	Double
Average_Distance	The average N neighbor distance.	Double
Maximum_Distance	The maximum N neighbor distance.	Double

Code sample

CalculateDistanceBand example 1 (Python window)

The following Python Window script demonstrates how to use the CalculateDistanceBand function.

import arcpy
arcpy.env.workspace = "c:/data"
mindist, avgdist, maxdist = arcpy.stats.CalculateDistanceBand("Blocks", 10, "EUCLIDEAN_DISTANCE")

CalculateDistanceBand example 2 (stand-alone script)

The following stand-alone Python script demonstrates how to use the CalculateDistanceBand function.

# import module
import arcpy

# Set geoprocessing workspace environment
arcpy.env.workspace = "c:/data"

# Set variables 
infc = "Blocks"
field = "POP2000"
outfc = "PopHotSpots"
neighbors = 10

# Run the CalculateDistanceBand tool to get a distance for use with the Hot Spot 
# tool from the tool result object
mindist, avgdist, maxdist = arcpy.stats.CalculateDistanceBand(infc, neighbors, 
                                                              "EUCLIDEAN_DISTANCE")
 
# Run the Hot Spot Analysis tool, using the maxdist output from the Calculate 
# Distance Band tool as an input
arcpy.stats.HotSpots(infc, field, outfc, "Fixed Distance Band", 
                        "EUCLIDEAN_DISTANCE", "None", maxdist)

Environments

Current Workspace, Scratch Workspace, Output Coordinate System, Geographic Transformations

Special cases

Output Coordinate System

Feature geometry is projected to the Output Coordinate System prior to analysis. All mathematical computations are based on the Output Coordinate System spatial reference. When the Output Coordinate System is based on degrees, minutes, and seconds, geodesic distances are estimated using chordal distances.