ArcMap

Polygon Neighbors

Summary

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

Learn more about how Polygon Neighbors works

Illustration

Diagram showing a source polygon and its neighbor polygons

Usage

  • The tool analyzes polygon contiguity, summarizing 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)
    between source polygons and neighbor polygons. 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 above ways.

  • 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 Field(s) parameter (in_fields in Python) 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 using 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.

  • Include area overlap can be used if you want area overlapping relationships to be analyzed. When Include area overlap is selected, the output table contains a field called AREA that holds the area of overlap for the overlapping neighbor being analyzed. If no overlap is found, AREA is 0.

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

  • The Include both sides of neighbor relationship check box on the tool dialog box 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 (both_sides="BOTH_SIDES" in Python). 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 to use 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 Area Overlap parameter is checked (area_overlap="AREA_OVERLAP" in Python). When Area Overlap 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 can be a file geodatabase table, personal geodatabase table, or .dbf table.

  • The output table contains the following fields:

    • src_field(s)—The prefix src stands for source, and field is a field specified in the Report By Field(s) parameter. You get as many fields as you specify in the Report By Field(s) parameter.
    • nbr_field(s)—The prefix nbr stands for neighbor, and field is a field specified in the Report By Field(s) parameter. Similar to src_field(s), you get as many fields as you specify in the Report By Field(s) parameter.
    • 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 overlap parameter is checked (area_overlap="AREA_OVERLAP" in Python ).
    • 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 are analyzed.

Syntax

PolygonNeighbors_analysis (in_features, out_table, {in_fields}, {area_overlap}, {both_sides}, {cluster_tolerance}, {out_linear_units}, {out_area_units})
ParameterExplanationData Type
in_features

The input polygon features.

Feature Layer
out_table

The output table.

Table
in_fields
[field,...]
(Optional)

Input attribute field or fields used to identify unique polygons or polygon groups and represent them in the output.

Field
area_overlap
(Optional)

Determines if overlapping polygons will be analyzed and reported in the output.

  • NO_AREA_OVERLAP —Overlapping relationships will not be analyzed and included in the output. This is the default.
  • AREA_OVERLAP —Overlapping relationships will be analyzed and included in the output.
Boolean
both_sides
(Optional)

Determines if both sides of neighbor relationships will be included in the output.

  • BOTH_SIDES — For a pair of neighboring polygons, report both neighboring information of one polygon being the source and the other being the neighbor and vice versa. This is the default.
  • NO_BOTH_SIDES — For a pair of neighboring polygons, only report neighboring information of one polygon being the source and the other being the neighbor. Do not include the reciprocal relationship.
Boolean
cluster_tolerance
(Optional)

The minimum distance between coordinates before they are considered equal. By default, this is the XY Tolerance of the input features.

Linear Unit
out_linear_units
(Optional)

Units used to report the total length of the coincident edge between neighboring polygons. The default is the input feature units.

  • UNKNOWN —Unknown
  • INCHES —Inches
  • FEET —Feet
  • YARDS —Yards
  • MILES —Miles
  • NAUTICAL_MILES —Nautical miles
  • MILLIMETERS —Millimeters
  • CENTIMETERS —Centimeters
  • DECIMETERS —Decimeters
  • METERS —Meters
  • KILOMETERS —Kilometers
  • DECIMAL_DEGREES —Decimal degrees
  • POINTS —Points
String
out_area_units
(Optional)

Units used to report the area overlap of neighboring polygons. The default is the input feature units. This parameter is only enabled when area_overlap="AREA_OVERLAP".

  • UNKNOWN —Unknown
  • ARES —Ares
  • ACRES —Acres
  • HECTARES —Hectares
  • SQUARE_INCHES —Square inches
  • SQUARE_FEET —Square feet
  • SQUARE_YARDS —Square yards
  • SQUARE_MILES —Square miles
  • SQUARE_MILLIMETERS —Square millimeters
  • SQUARE_CENTIMETERS —Square centimeters
  • SQUARE_DECIMETERS —Square decimeters
  • SQUARE_METERS —Square meters
  • SQUARE_KILOMETERS —Square kilometers
String

Code sample

PolygonNeighbors example (Python window)

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

import arcpy

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

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

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

Environments

Licensing information

  • ArcGIS Desktop Basic: Yes
  • ArcGIS Desktop Standard: Yes
  • ArcGIS Desktop Advanced: Yes

Related topics