Polygon Neighbors (Analysis)

Summary

Creates a table with statistics based on polygon contiguity (overlaps, coincident edges, or nodes).

Learn more about how Polygon Neighbors works

Illustration

A diagram of a source polygon and its neighbor polygons is shown.

Usage

• The tool analyzes polygon contiguity, summarizing the following between source polygons and neighbor polygons:

  • The area of overlaps (overlapping neighbors—optional)
  • The length of coincident edges (edge neighbors)
  • The number of times boundaries cross or touch at a point (node neighbors)
  The summary information is written to an output table. A source polygon may have one or more neighbor polygons; a neighbor polygon is spatially related with the source polygon in at least one of the ways described above.

• Only first-order contiguity is analyzed and reported by the tool. Relationships beyond that are not examined, that is, neighbors of neighbors (second-order contiguity) are not examined.

• The Report By Fields parameter is used to identify unique polygons or polygon groups and report their neighboring information by the polygons or polygon groups. To find the neighbors of each individual polygon in the input, specify one or more input fields that result in a unique value or set of values (in the case of multiple fields) for every polygon.

  If the specified fields identify unique polygon groups, the neighboring information is summarized and reported by the groups.

  See How Polygon Neighbors works for details on the use of this parameter.

• You can use the Include area overlaps parameter to analyze area overlapping relationships. When Include area overlaps is checked, the output table contains an AREA field that stores the area of overlap for the overlapping neighbor being analyzed. If no overlap is found, the AREA field value is 0.

  Tip:

  Calculating area overlapping relationships is a high-resource operation, and performance may be slower than determining coincident edge and node neighbor relationships. If you know your data has no overlapping features or you are not interested in analyzing overlapping neighbors, ensure that the Include area overlaps parameter is not checked.

  Caution:

  The Include area overlaps parameter must be checked to obtain records for neighbors that are completely contained by a source polygon. If the Include area overlaps parameter is not checked, the output table will not contain records for neighbors that are completely contained in a source polygon.

• There is no entry in the output table for features that are not neighbors.

• The Include both sides of neighbor relationship parameter is used to control the relationships included in the output. To report all contiguity relationships, including reciprocal relationships, check Include both sides of neighbor relationship. For example, if OID1 is a neighbor of OID2, an entry is written to the output table for OID1 having a neighbor OID2 and for OID2 having a neighbor OID1. If you only want the first side of the relationship, uncheck Include both sides of neighbor relationship. Using the example above but with Include both sides of neighbor relationship unchecked, only the entry for OID1 having a neighbor OID2 is entered into the output table.

• Output Linear Units specifies the units that will be used for shared boundary length between neighbors. The default is to use the same units as defined by the input feature coordinate system.

• Output Area Units is only used when the Include area overlaps parameter is checked. When Include area overlaps is checked, the units used to calculate the area overlap of neighbors are specified in the Output Area Units parameter. The default is to use the same units as defined by the input feature's coordinate system.

• The Output Table parameter value can be a file geodatabase table or .dbf table.

• For each field specified in the Report By Fields parameter, the output table will contain two fields using the following naming convention: src_<field> and nbr_<field>. The fields represent the source and neighbor field values from the input.

  The output table will also contain the following fields:

  • AREA—This field stores the total overlapping area between a source polygon and a neighbor polygon (overlapping neighbors). This field is included in the output table only when the Include area overlaps parameter is checked.
  • LENGTH—This field stores the total length of coincident edges between a source polygon and a neighbor polygon.
  • NODE_COUNT—This field stores the number of times a source polygon and a neighbor polygon cross or touch at a point.

• If there is a selection set on the input features, only selected features will be analyzed.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The input polygon features.	Feature Layer
Output Table	The output table.	Table
Report By Fields (Optional)	The input attribute field or fields that will be used to identify unique polygons or polygon groups and represent them in the output.	Field
Include area overlaps (Optional)	Specifies whether overlapping area relationships will be analyzed and included in the output. Unchecked—Overlapping relationships will not be analyzed or included in the output. This is the default. Checked—Overlapping relationships will be analyzed and included in the output.	Boolean
Include both sides of neighbor relationship (Optional)	Specifies whether both sides of neighbor relationships will be included in the output. Checked—For a pair of neighboring polygons, both neighboring information of one polygon being the source and the other being the neighbor and vice versa will be included. This is the default. Unchecked—For a pair of neighboring polygons, only neighboring information of one polygon being the source and the other being the neighbor will be included. The reciprocal relationship will not be included.	Boolean
XY Tolerance (Optional)	The minimum distance between coordinates before they will be considered equal. By default, this is the x,y tolerance of the input features. Caution: Changing this parameter's value may cause failure or unexpected results. It is recommended that you do not modify this parameter. It has been removed from view on the tool dialog box. By default, the input feature class's spatial reference x,y tolerance property is used.	Linear Unit
Output Linear Units (Optional)	Specifies the units that will be used to report the total length of the coincident edge between neighboring polygons. The default is the input feature units. Unknown—The length unit will be unknown. Kilometers—The length unit will be kilometers. Meters—The length unit will be meters. Decimeters—The length unit will be decimeters. Centimeters—The length unit will be centimeters. Millimeters—The length unit will be millimeters. Statute Miles—The length unit will be statute miles. International Nautical Miles—The length unit will be international nautical miles. International Yards—The length unit will be international yards. International Feet—The length unit will be international feet. International Inches—The length unit will be international inches. US Survey Miles—The length unit will be US survey miles. US Survey Nautical Miles—The length unit will be US survey nautical miles. US Survey Yards—The length unit will be US survey yards. US Survey Feet—The length unit will be US survey feet. US Survey Inches—The length unit will be US survey inches. Decimal Degrees—The length unit will be decimal degrees. Points—The length unit will be points.	String
Output Area Units (Optional)	Specifies the units that will be used to report the area overlap of neighboring polygons. The default is the input feature units. This parameter is only active when the Include area overlaps parameter is checked. Unknown—The area unit will be square unknown. Square Kilometers—The area unit will be square kilometers. Square Meters—The area unit will be square meters. Square Decimeters—The area unit will be square decimeters. Square Centimeters—The area unit will be square centimeters. Square Millimeters—The area unit will be square millimeters. Square Statute Miles—The area unit will be square statute miles. Square International Yards—The area unit will be square international yards. Square International Feet—The area unit will be square international feet. Square International Inches—The area unit will be square international inches. Square US Survey Miles—The area unit will be square US survey miles. Square US Survey Yards—The area unit will be square US survey yards. Square US Survey Feet—The area unit will be square US survey feet. Square US Survey Inches—The area unit will be square US survey inches. US Survey Acres—The area unit will be US survey acres. Hectares—The area unit will be hectares. Acres—The area unit will be international acres. Ares—The area unit will be ares.	String

Python

arcpy.analysis.PolygonNeighbors(in_features, out_table, {in_fields}, {area_overlap}, {both_sides}, {cluster_tolerance}, {out_linear_units}, {out_area_units})

Name	Explanation	Data Type
in_features	The input polygon features.	Feature Layer
out_table	The output table.	Table
in_fields [in_fields,...] (Optional)	The input attribute field or fields that will be used to identify unique polygons or polygon groups and represent them in the output.	Field
area_overlap (Optional)	Specifies whether overlapping relationships will be analyzed and included in the output. NO_AREA_OVERLAP—Overlapping relationships will not be analyzed or included in the output. This is the default. AREA_OVERLAP—Overlapping relationships will be analyzed and included in the output.	Boolean
both_sides (Optional)	Specifies whether both sides of neighbor relationships will be included in the output. BOTH_SIDES— For a pair of neighboring polygons, both neighboring information of one polygon being the source and the other being the neighbor and vice versa will be included. This is the default. NO_BOTH_SIDES— For a pair of neighboring polygons, only neighboring information of one polygon being the source and the other being the neighbor will be included. The reciprocal relationship will not be included.	Boolean
cluster_tolerance (Optional)	The minimum distance between coordinates before they will be considered equal. By default, this is the x,y tolerance of the input features. Caution: Changing this parameter's value may cause failure or unexpected results. It is recommended that you do not modify this parameter. It has been removed from view on the tool dialog box. By default, the input feature class's spatial reference x,y tolerance property is used.	Linear Unit
out_linear_units (Optional)	Specifies the units that will be used to report the total length of the coincident edge between neighboring polygons. The default is the input feature units. UNKNOWN—The length unit will be unknown. KILOMETERS—The length unit will be kilometers. METERS—The length unit will be meters. DECIMETERS—The length unit will be decimeters. CENTIMETERS—The length unit will be centimeters. MILLIMETERS—The length unit will be millimeters. MILES_INTERNATIONAL—The length unit will be statute miles. NAUTICAL_MILES_INTERNATIONAL—The length unit will be international nautical miles. YARDS_INTERNATIONAL—The length unit will be international yards. FEET_INTERNATIONAL—The length unit will be international feet. INCHES_INTERNATIONAL—The length unit will be international inches. MILES—The length unit will be US survey miles. NAUTICAL_MILES—The length unit will be US survey nautical miles. YARDS—The length unit will be US survey yards. FEET—The length unit will be US survey feet. INCHES—The length unit will be US survey inches. DECIMAL_DEGREES—The length unit will be decimal degrees. POINTS—The length unit will be points.	String
out_area_units (Optional)	Specifies the units that will be used to report the area overlap of neighboring polygons. The default is the input feature units. This parameter is only enabled when the area_overlap parameter is set to AREA_OVERLAP. UNKNOWN—The area unit will be square unknown. SQUARE_KILOMETERS—The area unit will be square kilometers. SQUARE_METERS—The area unit will be square meters. SQUARE_DECIMETERS—The area unit will be square decimeters. SQUARE_CENTIMETERS—The area unit will be square centimeters. SQUARE_MILLIMETERS—The area unit will be square millimeters. SQUARE_MILES—The area unit will be square statute miles. SQUARE_YARDS—The area unit will be square international yards. SQUARE_FEET—The area unit will be square international feet. SQUARE_INCHES—The area unit will be square international inches. SQUARE_MILES_US—The area unit will be square US survey miles. SQUARE_YARDS_US—The area unit will be square US survey yards. SQUARE_FEET_US—The area unit will be square US survey feet. SQUARE_INCHES_US—The area unit will be square US survey inches. ACRES_US—The area unit will be US survey acres. HECTARES—The area unit will be hectares. ACRES—The area unit will be international acres. ARES—The area unit will be ares.	String

Code sample

PolygonNeighbors example (Python window)

Find each electoral district's neighbors in the province of Nova Scotia.

import arcpy

arcpy.management.MakeFeatureLayer(r"C:\Data\Canada\CanadaElecDist.shp", 
                                  "Canada_ElectoralDist")

arcpy.management.SelectLayerByAttribute("Canada_ElectoralDist", "NEW_SELECTION", 
                                        "\"PROVCODE\" = 'NS'")
count = arcpy.management.GetCount("Canada_ElectoralDist")[0]
print("Selected feature count: {}".format(count))

arcpy.analysis.PolygonNeighbors("Canada_ElectoralDist", 
                                r"C:\Data\Output\NS_elec_neigh.dbf", "ENNAME")
print(arcpy.GetMessages())

Environments

Auto Commit, Qualified Field Names, Extent, Scratch Workspace, Current Workspace

Licensing information

• Basic: Yes
• Standard: Yes
• Advanced: Yes