Summary
Finds clusters of point features in surrounding noise based on their spatial or spatiotemporal distribution.
Illustration
Usage
This geoprocessing tool is available with ArcGIS Enterprise 10.6.1 or later.
The input for Find Point Clusters is a point layer. This tool extracts clusters from the Input Point Layer and identifies any surrounding noise.
Find Point Clusters requires that Input Point Layer is projected or the output coordinate system is set to a projected coordinate system.
There are two Clustering Method parameter options. Defined distance (DBSCAN) uses the DBSCAN algorithm and finds clusters of points that are in close proximity based on a specified search distance. Self-adjusting (HDBSCAN) uses the HDBSCAN algorithm (available with ArcGIS Enterprise 10.7 and later) and finds clusters of points, similar to DBSCAN, using varying distances, allowing for clusters with varying densities based on cluster probability (or stability). If DBSCAN is chosen, clusters can be found in either two-dimensional space only or both in space and time. If you check Use time to find clusters and the input layer has time enabled and is of type instant, DBSCAN will discover spatiotemporal clusters of points that are in close proximity based on a specified search distance and search duration (supported with ArcGIS Enterprise 10.8 and later).
The Minimum Features per Cluster parameter is used differently, depending on the clustering method:
- Defined distance (DBSCAN)—Specifies the number of features that must be found within a search distance of a point for that point to start forming a cluster. The results may include clusters with fewer features than this value. The search distance is set using the Search Distance parameter. When using time to find clusters, Search Duration is required. When searching for cluster members, Minimum Features per Cluster must be found within Search Distance and Search Duration to form a cluster. Note that this distance and duration are not related to the diameter or time extent of the point clusters discovered.
- Self-adjusting (HDBSCAN)—Specifies the number of features neighboring each point (including the point) that will be considered when estimating density. This number is also the minimum cluster size allowed when extracting clusters.
This tool produces an output feature class with a new integer field, CLUSTER_ID, that identifies the cluster where each feature is located. Default rendering is based on the COLOR_ID field. Multiple clusters will be assigned each color. Colors will be assigned and repeated so that each cluster is visually distinct from its neighboring clusters.
If the Defined distance (DBSCAN) clustering method is used with time to discover spatiotemporal clusters, results will also include the following fields:
- FEAT_TIME —The original instant time of each feature.
- START_DATETIME—The start time of the time extent of the cluster a feature belongs to.
- END_DATETIME—The end time of the time extent of the cluster a feature belongs to.
The result layer's time properties will be set as an interval on the START_DATETIME and END_DATETIME fields, ensuring that all cluster members are drawn together when visualizing spatiotemporal clusters with a time slider. These fields are used for visualization only. For noise features, START_DATETIME and END_DATETIME will be equal to FEAT_TIME.
If Clustering Method is Self-adjusting (HDBSCAN), the output feature class will also contain the following fields:
- PROB—The probability that a feature belongs in its assigned cluster.
- OUTLIER—The likelihood that a feature is an outlier within its own cluster. A larger value indicates that the feature is more likely to be an outlier.
- EXEMPLAR—The features that are most representative of each cluster. These features are indicated by a value of 1.
- STABILITY—The persistence of each cluster across a range of scales. A larger value indicates that a cluster persists over a wider range of distance scales.
When using the HDBSCAN algorithm with an input layer containing more than 3 million features, the tool may fail unless your administrator increases the value of the javaHeapSize parameter on the GeoAnalyticsTools GP Service. Approximately 2 GB of heap space is needed per 3 million features. The amount of RAM specified by javaHeapSize should be available on each GeoAnalytics Server machine in addition to the 16 GB typically required by GeoAnalytics Server. For example, to cluster 9 million features with HDBSCAN, set javaHeapSize to no less than 6144 MB, or 6 GB. In this case, each GeoAnalytics Server machine should have a total of at least 22 GB of RAM available.
You can improve the performance of the Find Point Clusters tool by using one or more of the following tips:
- Set the extent environment so you only analyze data of interest.
- Be selective in the search distance and duration. A narrower search distance or radius may perform better on the same data.
- Use data that is local to where the analysis is being run.
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. Therefore, 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
Syntax
arcpy.geoanalytics.FindPointClusters(input_points, output_name, minimum_points, search_distance, {data_store}, {clustering_method}, {use_time}, {search_duration})| Parameter | Explanation | Data Type |
input_points | The point feature class containing the point clusters. | Feature Set |
output_name | The name of the output feature service. | String |
minimum_points | This parameter is used differently depending on the clustering method chosen as follows:
| Long |
search_distance | The maximum distance to be considered. The Minimum Features per Cluster specified must be found within this distance for cluster membership. Individual clusters will be separated by at least this distance. If a feature is located farther than this distance from the next closest feature in the cluster, it will not be included in the cluster. | Linear 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.
| String |
clustering_method (Optional) | Specifies the method that will be used to define clusters.
| String |
use_time (Optional) | Specifies whether or not time will be used to discover clusters with DBSCAN.
| Boolean |
search_duration (Optional) | When searching for cluster members, the specified minimum number of points must be found within this time duration to form a cluster. | Time Unit |
Derived Output
| Name | Explanation | Data Type |
| output | The output point clusters. | Feature Set |
Code sample
The following Python window script demonstrates how to use the FindPointClusters tool.
#-------------------------------------------------------------------------------
# Name: FindPointClusters.py
# Description: Finds Point Clusters of rodent infestations
#
# Requirements: ArcGIS GeoAnalytics Server
# Import system modules
import arcpy
# Set local variables
inputPoints = "https://myGeoAnalyticsMachine.domain.com/geoanalytics/rest/services/DataStoreCatalogs/bigDataFileShares_countyData/BigDataCatalogServer/rat_sightings"
minimumPoints = 10
outputName = "RodentClusters"
searchDistance = "1 Kilometers"
dataStore = "SPATIOTEMPORAL_DATA_STORE"
clusterMethod = "DBSCAN"
# Execute Find Point Clusters
arcpy.geoanalytics.FindPointClusters(inputPoints, outputName, mimimumPoints,
searchDistance, dataStore, clusterMethod)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