Multi-Distance Spatial Cluster Analysis (Ripley's K Function) (Spatial Statistics)

License Level:BasicStandardAdvanced

Summary

Determines whether features, or the values associated with features, exhibit statistically significant clustering or dispersion over a range of distances.

Learn more about how Multi-Distance Spatial Cluster Analysis works

Illustration

K Function Graphic
Measure of spatial clustering/dispersion over a range of distances.

Usage

Syntax

MultiDistanceSpatialClustering_stats (Input_Feature_Class, Output_Table, Number_of_Distance_Bands, {Compute_Confidence_Envelope}, {Display_Results_Graphically}, {Weight_Field}, {Beginning_Distance}, {Distance_Increment}, {Boundary_Correction_Method}, {Study_Area_Method}, {Study_Area_Feature_Class})
ParameterExplanationData Type
Input_Feature_Class

The feature class upon which the analysis will be performed.

Feature Layer
Output_Table

The table to which the results of the analysis will be written.

Table
Number_of_Distance_Bands

The number of times to increment the neighborhood size and analyze the dataset for clustering. The starting point and size of the increment are specified in the Beginning Distance and Distance Increment parameters, respectively.

Long
Compute_Confidence_Envelope
(Optional)

The confidence envelope is calculated by randomly placing feature points (or feature values) in the study area. The number of points/values randomly placed is equal to the number of points in the feature class. Each set of random placements is called a "permutation" and the confidence envelope is created from these permutations. This parameter allows you to select how many permutations you want to use to create the confidence envelope.

  • 0_PERMUTATIONS_-_NO_CONFIDENCE_ENVELOPEConfidence envelopes are not created.
  • 9_PERMUTATIONSNine sets of points/values are randomly placed.
  • 99_PERMUTATIONS99 sets of points/values are randomly placed.
  • 999_PERMUTATIONS999 sets of points/values are randomly placed.
String
Display_Results_Graphically
(Optional)
  • NO_DISPLAYNo graphical summary will be created (default).
  • DISPLAY_ITA graphical summary will be created as a graph layer.
Boolean
Weight_Field
(Optional)

A numeric field with weights representing the number of features/events at each location.

Field
Beginning_Distance
(Optional)

The distance at which to start the cluster analysis and the distance from which to increment. The value entered for this parameter should be in the units of the Output Coordinate System.

Double
Distance_Increment
(Optional)

The distance to increment during each iteration. The distance used in the analysis starts at the Beginning Distance and increments by the amount specified in the Distance Increment. The value entered for this parameter should be in the units of the Output Coordinate System.

Double
Boundary_Correction_Method
(Optional)

Method to use to correct for underestimates in the number of neighbors for features near the edges of the study area.

  • NONENo edge correction is applied. However, if the input feature class already has points that fall outside the study area boundaries, these will be used in neighborhood counts for features near boundaries.
  • SIMULATE_OUTER_BOUNDARY_VALUESThis method simulates points outside the study area so that the number of neighbors near edges is not underestimated. The simulated points are the "mirrors" of points near edges within the study area boundary.
  • REDUCE_ANALYSIS_AREAThis method shrinks the study area such that some points are found outside of the study area boundary. Points found outside the study area are used to calculate neighbor counts but are not used in the cluster analysis itself.
  • RIPLEY'S_EDGE_CORRECTION_FORMULAFor all the points (j) in the neighborhood of point i, this method checks to see if the edge of the study area is closer to i, or if j is closer to i. If j is closer, extra weight is given to the point j. This edge correction method is only appropriate for square or rectangular shaped study areas.
String
Study_Area_Method
(Optional)

Specifies the region to use for the study area. The K Function is sensitive to changes in study area size so careful selection of this value is important.

  • MINIMUM_ENCLOSING_RECTANGLEIndicates that the smallest possible rectangle enclosing all of the points will be used.
  • USER_PROVIDED_STUDY_AREA_FEATURE_CLASSIndicates that a feature class defining the study area will be provided in the Study Area Feature Class parameter.
String
Study_Area_Feature_Class
(Optional)

Feature class that delineates the area over which the input feature class should be analyzed. Only to be specified if User-provided Study Area Feature Class is selected for the Study Area Method parameter.

Feature Layer

Code Sample

Multi-DistanceSpatialClusterAnalysis Example (Python Window)

The following Python Window script demonstrates how to use the Multi-DistanceSpatialClusterAnalysis tool.

import arcpy
arcpy.env.workspace = r"C:\data"
arcpy.MultiDistanceSpatialClustering_stats("911Calls.shp","kFunResult.dbf", 11,
                                           "0_PERMUTATIONS_-_NO_CONFIDENCE_ENVELOPE",
                                           "NO_REPORT", "#", 1000, 200,"REDUCE_ANALYSIS_AREA",
                                           "MINIMUM_ENCLOSING_RECTANGLE", "#")
Multi-DistanceSpatialClusterAnalysis Example (stand-alone Python script)

The following stand-alone Python script demonstrates how to use the Multi-DistanceSpatialClusterAnalysis tool.

# Use Ripley's K-Function to analyze the spatial distribution of 911
# calls in Portland Oregon 

# Import system modules
import arcpy

# Set the geoprocessor object property to overwrite existing outputs
arcpy.gp.overwriteOutput = True

# Local variables...
workspace = r"C:\Data"

try:
    # Set the current workspace (to avoid having to specify the full path to the feature classes each time)
    arcpy.env.workspace = workspace

    # Set Distance Band Parameters: Analyze clustering of 911 calls from
    # 1000 to 3000 feet by 200 foot increments
    numDistances = 11
    startDistance = 1000.0
    increment = 200.0

    # Process: Run K-Function...
    kFun = arcpy.MultiDistanceSpatialClustering_stats("911Calls.shp",
                        "kFunResult.dbf", numDistances,
                        "0_PERMUTATIONS_-_NO_CONFIDENCE_ENVELOPE", 
                        "NO_REPORT", "#", startDistance, increment,
                        "REDUCE_ANALYSIS_AREA",
                        "MINIMUM_ENCLOSING_RECTANGLE", "#")

except:
    # If an error occurred when running the tool, print out the error message.
    print arcpy.GetMessages()

Environments

Output Coordinate System

Feature geometry is projected to the Output Coordinate System prior to analysis, so values entered for the Beginning Distance and Distance Increment parameters should match those specified in the Output Coordinate System. All mathematical computations are based on the Output Coordinate System spatial reference.

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Yes
ArcGIS for Desktop Standard: Yes
ArcGIS for Desktop Advanced: Yes
4/18/2013