Group By Proximity (GeoAnalytics Desktop)

Summary

Groups features that are within spatial or spatiotemporal proximity to each other.

The following are examples of questions that can be answered by Group By Proximity workflows:

  • Which roads are connected?
  • Where are there groups of crime that happened within a close distance and time of each other?
  • Are there groups of polygons that overlap each other?

Illustration

Group By Proximity tool illustration

Usage

  • The output result is a copy of the input with a new field named group_id. The group_id field represents the grouping of features. Features with the same group_id value are in the same group. The group numbers represent membership in a particular group and don't imply value. The group numbers may not be sequential or the same number in repeat use of the tool. Results will be symbolized with eight groups. If there are more than eight groups in the result, all groups will be symbolized with eight colors by default. You can modify the symbology to show each unique group by symbolizing with unique symbols on the group_id field.

  • The tool supports the following combinations of relationships:

    • A spatial relationship
    • A spatial relationship and a temporal relationship
    • A spatial relationship and an attribute relationship
    • A spatial relationship, a temporal relationship, and an attribute relationship
    Features are grouped when all specified relationships are met.

  • The supported spatial relationships and input geometries are described in the following table:

    Input geometry typeIntersectsTouchesGeodesic NearPlanar Near

    Point

    Check markCheck markCheck mark

    Polyline

    Check markCheck markCheck markCheck mark

    Polygon

    Check markCheck markCheck markCheck mark

    Overlay methodDescription

    Intersects

    Features intersect when features or portions of features overlap. This is the default.

    Touches

    Features touch another feature if they have an intersecting vertex, but the features do not overlap.

    Geodesic Near

    Features are near if a vertex or edge is within a given geodesic distance of another feature.

    Planar Near

    Features are near if a vertex or edge is within a given planar distance of another feature.

  • To use the Spatial Relationship parameter's Planar Near option, the Input Layer parameter value must be projected or the output coordinate system is set to a projected coordinate system.

  • The supported temporal relationships and temporal types are described in the following table:

    Input temporal typeIntersectsNear

    None

    Instant

    Check markCheck mark

    Interval

    Check markCheck mark

    Temporal relationship methodDescription

    Intersects

    Features intersect when any part of a feature's time overlaps another.

    Near

    Features are near one another if a feature's time is within a given time distance of another feature.

  • To use a temporal relationship, you must enable time on the input. You can enable time by doing the following:

  • Attribute expressions are a symmetric operation. The tool takes a single input layer that is compared to itself when grouping. Because of this, the input layer is denoted as both a and b in the ArcGIS Arcade expression, and all expressions need to include both a and b. For example, to group all records when the Amount field has the same value, use the following expression: $a["Amount"] == $b["Amount"].

  • You can improve performance of the Group By Proximity tool by doing one or more of the following:

    • Set the extent environment so that you only analyze data of interest.
    • When using the Spatial Relationship parameter's Planar Near or Geodesic Near option, use a smaller Spatial Near Distance parameter value.
    • When using the Spatial Relationship parameter, the Planar Near option is faster than the Geodesic Near option.
    • When using the Temporal Relationship parameter's Near option, use a smaller Temporal Near Distance parameter value.
    • Use data that is local to where the analysis is being run.

  • This geoprocessing tool is powered by Spark. Analysis is completed on your desktop machine using multiple cores in parallel. See Considerations for GeoAnalytics Desktop tools to learn more about running analysis.

  • When running GeoAnalytics Desktop tools, the analysis is completed on your desktop machine. For optimal performance, data should be available on your desktop. If you are using a hosted feature layer, it is recommended that you use ArcGIS GeoAnalytics Server. If your data isn't local, it will take longer to run a tool. To use your ArcGIS GeoAnalytics Server to perform analysis, see GeoAnalytics Tools.

Parameters

LabelExplanationData Type
Input Layer

The point, line, or polygon features that will be grouped.

Feature Layer
Output

The output feature class with grouped features represented by a new field named group_id.

Feature Class
Spatial Relationship

Specifies the type of relationship that features will be grouped by.

  • IntersectsFeatures will be grouped when features or portions of features overlap. This is the default.
  • TouchesFeatures will be grouped with another feature if they have an intersecting vertex, but the features do not overlap.
  • Planar NearFeatures will be grouped when a vertex or edge is within a given planar distance of another feature.
  • Geodesic NearFeatures will be grouped when a vertex or edge is within a given geodesic distance of another feature.
String
Spatial Near Distance
(Optional)

The distance that will be used to group near features. This parameter is only used when the Spatial Relationship parameter value is Planar Near or Geodesic Near.

Linear Unit
Temporal Relationship
(Optional)

Specifies the time criteria that will be used to match features. When the parameter is set to Intersects or Near, features are grouped when both the spatial and time criteria are met. Time must be enabled on the input to support this option.

  • IntersectsFeatures will be grouped when any part of a feature's time overlaps another feature. This is the default.
  • NearFeatures will be grouped when the feature's time is within a range of time of another feature.
  • NoneTime will not be used to group features.
String
Temporal Near Distance
(Optional)

The temporal distance that will be used to group near features. This parameter is only used when the Temporal Relationship parameter value is Near.

Time Unit
Attribute Relationship
(Optional)

An ArcGIS Arcade expression that will be used to group features by. For example, $a["Amount"] == $b["Amount"] groups features when the Amount field has the same value.

String

arcpy.geoanalytics.GroupByProximity(input_layer, output, spatial_relationship, {spatial_near_distance}, {temporal_relationship}, {temporal_near_distance}, {attribute_relationship})
NameExplanationData Type
input_layer

The point, line, or polygon features that will be grouped.

Feature Layer
output

The output feature class with grouped features represented by a new field named group_id.

Feature Class
spatial_relationship

Specifies the type of relationship that features will be grouped by.

  • INTERSECTSFeatures will be grouped when features or portions of features overlap. This is the default.
  • TOUCHESFeatures will be grouped with another feature if they have an intersecting vertex, but the features do not overlap.
  • NEAR_PLANARFeatures will be grouped when a vertex or edge is within a given planar distance of another feature.
  • NEAR_GEODESICFeatures will be grouped when a vertex or edge is within a given geodesic distance of another feature.
String
spatial_near_distance
(Optional)

The distance that will be used to group near features. This parameter is only used when the spatial_relationship parameter value is NEAR_PLANAR or NEAR_GEODESIC.

Linear Unit
temporal_relationship
(Optional)

Specifies the time criteria that will be used to match features. When the parameter is set to INTERSECTS or NEAR, features are grouped when both the spatial and time criteria are met. Time must be enabled on the input to support this option.

  • INTERSECTSFeatures will be grouped when any part of a feature's time overlaps another feature. This is the default.
  • NEARFeatures will be grouped when the feature's time is within a range of time of another feature.
  • NONETime will not be used to group features.
String
temporal_near_distance
(Optional)

The temporal distance that will be used to group near features. This parameter is only used when the temporal_relationship parameter value is Near.

Time Unit
attribute_relationship
(Optional)

An ArcGIS Arcade expression that will be used to group features by. For example, $a["Amount"] == $b["Amount"] groups features when the Amount field has the same value.

String

Code sample

GroupByProximity example (stand-alone script)

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

# Name: GroupByProximity.py
# Description: Group roads together that touch
#
# Requirements: An advanced license

# Import system modules
import arcpy

# Set local variables
inFeatures = "C:\myData\cities.gdb\roads"
outname = "groupedRoads"
overlayType = "TOUCHES"

# Run Group By Proximity
result = arcpy.gapro.GroupByProximity(inFeatures, outname, overlayType)