Group By Proximity (GeoAnalytics)

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

  • This geoprocessing tool is available with ArcGIS Enterprise 10.9.1 or later.

  • 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 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

    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.

  • 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.

  • You can specify a Spatial Relationship value without a Temporal Relationship value, or you can specify both. When you specify a spatial and temporal relationship (Intersects, Planar Near, or Geodesic Near), features are grouped when the spatial and temporal relationships are both true.

  • This geoprocessing tool is powered by ArcGIS GeoAnalytics Server. Analysis is completed on your GeoAnalytics Server, and results are stored in your content in ArcGIS Enterprise.

  • When running GeoAnalytics Server tools, the analysis is completed on the GeoAnalytics Server. For optimal performance, make data available to the GeoAnalytics Server through feature layers hosted on your ArcGIS Enterprise portal or through big data file shares. Data that is not local to your GeoAnalytics Server will be moved to your GeoAnalytics Server before analysis begins. This means that it will take longer to run a tool, and in some cases, moving the data from ArcGIS Pro to your GeoAnalytics Server may fail. The threshold for failure depends on your network speeds, as well as the size and complexity of the data. It is recommended that you always share your data or create a big data file share.

    Learn more about sharing data to your portal

    Learn more about creating a big data file share through Server Manager

Parameters

LabelExplanationData Type
Input Layer

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

Feature Set
Output Name

The name of the output feature service.

The name of the output feature service with grouped features represented by a new field named group_id

String
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
Data Store
(Optional)

Specifies the ArcGIS Data Store where the output will be saved. The default is Spatiotemporal big data store. All results stored in a spatiotemporal big data store will be stored in WGS84. Results stored in a relational data store will maintain their coordinate system.

  • Spatiotemporal big data storeOutput will be stored in a spatiotemporal big data store. This is the default.
  • Relational data storeOutput will be stored in a relational data store.
String

Derived Output

LabelExplanationData Type
Output Feature Layer

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

Feature Set

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

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

Feature Set
output_name

The name of the output feature service.

The name of the output feature service with grouped features represented by a new field named group_id

String
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
data_store
(Optional)

Specifies the ArcGIS Data Store where the output will be saved. The default is SPATIOTEMPORAL_DATA_STORE. All results stored in a spatiotemporal big data store will be stored in WGS84. Results stored in a relational data store will maintain their coordinate system.

  • SPATIOTEMPORAL_DATA_STOREOutput will be stored in a spatiotemporal big data store. This is the default.
  • RELATIONAL_DATA_STOREOutput will be stored in a relational data store.
String

Derived Output

NameExplanationData Type
output

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

Feature Set

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: ArcGIS GeoAnalytics Server

# Import system modules
import arcpy

# Set local variables
inFeatures = "https://myGeoAnalyticsMachine.domain.com/geoanalytics/rest/services/DataStoreCatalogs/bigDataFileShares_cityData/BigDataCatalogServer/roads"
outFS = "groupedRoads"
overlayType = "TOUCHES"
dataStore = "SPATIOTEMPORAL_DATA_STORE"

# Execute Group By Proximity
result = arcpy.geoanalytics.GroupByProximity(inFeatures, outFS, 
                                 overlayType, data_store=dataStore)

Environments

Output Coordinate System

The coordinate system that will be used for analysis. Analysis will be completed in the input coordinate system unless specified by this parameter. For GeoAnalytics Tools, final results will be stored in the spatiotemporal data store in WGS84.

Licensing information

  • Basic: Requires ArcGIS GeoAnalytics Server
  • Standard: Requires ArcGIS GeoAnalytics Server
  • Advanced: Requires ArcGIS GeoAnalytics Server

Related topics