com.esri.arcgis.geoprocessing.tools.spatialstatisticstools
Class MultiDistanceSpatialClustering

java.lang.Object
  com.esri.arcgis.geoprocessing.AbstractGPTool
      com.esri.arcgis.geoprocessing.tools.spatialstatisticstools.MultiDistanceSpatialClustering

All Implemented Interfaces:

GPTool

public class MultiDistanceSpatialClustering
extends AbstractGPTool

The Multi-Distance Spatial Cluster Analysis (Ripley's K-function) tool determines whether a feature class is clustered at multiple different distances. The tool outputs the result as a table and optionally as a pop up graphic. The Multi-Distance Spatial Cluster Analysis (Ripleys K Function) tool is contained in the Spatial Statistics Tools tool box.
Learn more about how Multi-Distance Spatial Cluster Analysis works.

Software restrictions: none

Illustration:

Usage tips:

• This tool honors the environment 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;
• The output of the tool is a table with fields named "ExpectedK" and "ObservedK" containing the expected k and observed k values respectively. A field named "DiffK" contains the observed K minus the expected K value. If a confidence interval option is specified two additional fields named "LwConfEnv" and "HiConfEnv" will be present with the confidence interval information for each iteration of the tool.
• When the observed K value is larger than the expected K value for a particular distance, the distribution is more clustered than a random distribution at that distance (scale of analysis). When the observed K value is smaller than the expected K, the distribution is more dispersed than a random distribution at that distance. When the observed K value is larger than the HiConfEnv value, spatial clustering for that distance is statistically significant. When the observed K value is smaller than the LwConfEnv value, spatial dispersion for that distance is statistically significant.
• The number of permutations selected may be loosely translated to confidence levels: 9 for 90%, 99 for 99%, and 999 for 99.9%.
• The largest DiffK value tells you the distance where spatial processes promoting clustering are most pronounced, and may be an appropriate distance to use for the Fixed Distance conceptualization of spatial relationships when running the Hot Spot; or Cluster/Outlier; Analyses.
• While this tool will work with line or polygon features, it is most appropriate for point features. If the input feature class does not contain points, feature centroids are used in computations. For multipoint, polyline or polygons with multiple parts, the centroid is computed using the weighted mean center of all feature parts. The weighted mean center for point features is 1, for line features is length, and for polygon features is area.
• Whenever using shapefiles keep in mind that they cannot store null values. Tools or other procedures that create shapefiles from non-shapefile inputs may store or interpret null values as zero. This can lead to unexpected results.
• The Weight Field is most appropriately used when it represents number of incidents or counts.
• When no weight field is specified, the confidence envelope is constructed by distributing points randomly in the study area and calculating k for that distribution. Each random distribution of the points is called a "permutation". If "99 permutations" is selected, the tool will randomly distribute the set of points 99 times for each iteration. After distributing the points 99 times the tool selects the k value that deviated above and below the expected by the greatest amount and these values become the confidence interval.
• When a weight field is specified, only the weight values are randomly redistributed to compute confidence envelopes; the point locations remain fixed. In essence, when a weight field is specified, locations remain fixed and we evaluate the clustering of feature values in space. On the other hand, when no weight field is specified we are analyzing clustering/dispersion of feature locations.
• When no study area is specified, the tool uses a minimum enclosing rectangle as the study area polygon. Unlike the extent; , a minimum enclosing rectangle will not necessarily align with the x- and y-axes.
• The k-function statistic is very sensitive to the size of the study area. Identical arrangments of points can exhibit clustering or dispersion depending on the size of the study area enclosing them. Therefore it is imperative that the study area boundaries are carefully considered. The picture below is a classic example of how identical feature distributions can be dispersed or clustered depending on the study area specified.
  
• A study area feature class should only be given if "User-provided Study Area Feature Class" is chosen for the Study Area Method parameter.
• If a study area feature class is specified, it should have exactly one single part feature.
• If no Beginning Distance or Increment Distance are specified then default values are calculated for you based on the extent of the input feature class.
• Points in the input feature class that fall outside the user specified study area are only considered when the "None" edge correction option is selected. Other edge correction techniques compensate for edge issues with simulated points, by reducing the study area, or by weighting edge neighbors higher than non-edge neighbors.
• The Simulate Outer Boundary Values edge correction method mirrors points across the study area boundary to correct for underestimates near edges. Points that are within a distance equal to the maximum distance band of the edge of the study area are mirrored. The mirrored points are used so that edge points will have more accurate neighbor estimates. The diagram below illustrates what points will be used in the calculation and which will be used only for edge correction.
  
• The Reduce Analysis Area edge correction technique shrinks the size of the analysis area by a distance equal to the largest distance band to be used in the analysis. After shrinking the study area, points found outside of the new study area will be considered only when neighbor counts are being assessed for points still inside the study area. They will not be used in any other way during the k-function calculation. The diagram below illustrates what points will be used in the calculation and which will be used only for edge correction.
  
• The Reduce Study Area Correction option is not valid with the user supplied study area polygon option for the Study Area parameter.
• Ripley's Edge Correction Formula checks each point's distance from the edge of the study area and its distance to each of its neighbors. All neighbors that are further away from the point in question than the edge of the study area are given extra weight. This edge correction method is only appropriate for square or rectangular shaped study areas.
• Mathematically, the Multi-Distance Spatial Cluster Analysis tool uses a common transformation of Ripley's k-function where the expected result with a random set of points is equal to the input distance. The transformation L(d) is shown below.
  
  where A is area, N is the number of points, d is the distance and k(i, j) is the weight, which (if there is no edge correction) is 1 when the distance between i and j is less than or equal to d and 0 when the distance between i and j is greater than d. When edge correction is applied, the weight of k(i,j) is modified slightly.
• When the "Display Output Graphically" option is chosen, a graph showing the expected and observed outputs for each iteration is generated and displayed. The expected results will be represented by a blue line while the observed results will be a red line. Deviation of the observed line above the expected line indicates that the dataset is exhibiting clustering at that distance. Deviation of the observed line below the expected line indicates that the dataset is exhibiting dispersion at that distance.
• The "Display Output Graphically" parameter will only work on the Windows operating system. When set to true it will display the results of the tool graphically.
• When output is shown graphically, a separate graphics dialog box will be displayed. If you use the tool in a script, set the Display_Output_Graphically parameter to "false", otherwise your script will not complete until you click"Close" on the popup graphic.
• Current map layers may be used to define the input feature class. When using layers, only the currently selected features are included in the analysis.
• Learn more about working with layers and table views;

Field Summary

Fields inherited from class com.esri.arcgis.geoprocessing.AbstractGPTool

vals

Constructor Summary

MultiDistanceSpatialClustering()
Creates the Multi-Distance Spatial Cluster Analysis (Ripleys K Function) tool with defaults.

MultiDistanceSpatialClustering(Object inputFeatureClass, Object outputTable, int numberOfDistanceBands)
Creates the Multi-Distance Spatial Cluster Analysis (Ripleys K Function) tool with the required parameters.

Method Summary

double	getBeginningDistance() Returns the Beginning Distance parameter of this tool .
String	getBoundaryCorrectionMethod() Returns the Boundary Correction Method parameter of this tool .
String	getComputeConfidenceEnvelope() Returns the Compute Confidence Envelope parameter of this tool .
String	getDisplayResultsGraphically() Returns the Display Results Graphically parameter of this tool .
double	getDistanceIncrement() Returns the Distance Increment parameter of this tool .
Object	getInputFeatureClass() Returns the Input Feature Class parameter of this tool .
int	getNumberOfDistanceBands() Returns the Number of Distance Bands parameter of this tool .
Object	getOutputTable() Returns the Output Table parameter of this tool .
Object	getStudyAreaFeatureClass() Returns the Study Area Feature Class parameter of this tool .
String	getStudyAreaMethod() Returns the Study Area Method parameter of this tool .
String	getToolboxAlias() Returns the alias of the tool box containing this tool.
String	getToolboxName() Returns the name of the tool box containing this tool.
String	getToolName() Returns the name of this tool.
Object	getWeightField() Returns the Weight Field parameter of this tool .
void	setBeginningDistance(double beginningDistance) Sets the Beginning Distance parameter of this tool .
void	setBoundaryCorrectionMethod(String boundaryCorrectionMethod) Sets the Boundary Correction Method parameter of this tool .
void	setComputeConfidenceEnvelope(String computeConfidenceEnvelope) Sets the Compute Confidence Envelope parameter of this tool .
void	setDisplayResultsGraphically(String displayResultsGraphically) Sets the Display Results Graphically parameter of this tool .
void	setDistanceIncrement(double distanceIncrement) Sets the Distance Increment parameter of this tool .
void	setInputFeatureClass(Object inputFeatureClass) Sets the Input Feature Class parameter of this tool .
void	setNumberOfDistanceBands(int numberOfDistanceBands) Sets the Number of Distance Bands parameter of this tool .
void	setOutputTable(Object outputTable) Sets the Output Table parameter of this tool .
void	setStudyAreaFeatureClass(Object studyAreaFeatureClass) Sets the Study Area Feature Class parameter of this tool .
void	setStudyAreaMethod(String studyAreaMethod) Sets the Study Area Method parameter of this tool .
void	setWeightField(Object weightField) Sets the Weight Field parameter of this tool .

Methods inherited from class com.esri.arcgis.geoprocessing.AbstractGPTool

getParameterValues, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MultiDistanceSpatialClustering

public MultiDistanceSpatialClustering()

Creates the Multi-Distance Spatial Cluster Analysis (Ripleys K Function) tool with defaults.

Initializes the array of tool parameters with the default values specified when the tool was created.

MultiDistanceSpatialClustering

public MultiDistanceSpatialClustering(Object inputFeatureClass,
                                      Object outputTable,
                                      int numberOfDistanceBands)

Creates the Multi-Distance Spatial Cluster Analysis (Ripleys K Function) tool with the required parameters.

Initializes the array of tool parameters with the values as specified for the required parameters and with the default values for the other parameters.

Parameters:

inputFeatureClass - Feature Class, the feature class upon which the analysis will be performed.

outputTable - Table, the table to which the results of the analysis will be written.

numberOfDistanceBands - Long, 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.

Method Detail

getInputFeatureClass

public Object getInputFeatureClass()

Returns the Input Feature Class parameter of this tool . This parameter is Feature Class, the feature class upon which the analysis will be performed. This is a required parameter.

Returns:

the Input Feature Class

setInputFeatureClass

public void setInputFeatureClass(Object inputFeatureClass)

Sets the Input Feature Class parameter of this tool . This parameter is Feature Class, the feature class upon which the analysis will be performed. This is a required parameter.

Parameters:

inputFeatureClass - Feature Class, the feature class upon which the analysis will be performed.

getOutputTable

public Object getOutputTable()

Returns the Output Table parameter of this tool . This parameter is Table, the table to which the results of the analysis will be written. This is a required parameter.

Returns:

the Output Table

setOutputTable

public void setOutputTable(Object outputTable)

Sets the Output Table parameter of this tool . This parameter is Table, the table to which the results of the analysis will be written. This is a required parameter.

Parameters:

outputTable - Table, the table to which the results of the analysis will be written.

getNumberOfDistanceBands

public int getNumberOfDistanceBands()

Returns the Number of Distance Bands parameter of this tool . This parameter is Long, 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. This is a required parameter.

Returns:

the Number of Distance Bands

setNumberOfDistanceBands

public void setNumberOfDistanceBands(int numberOfDistanceBands)

Sets the Number of Distance Bands parameter of this tool . This parameter is Long, 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. This is a required parameter.

Parameters:

numberOfDistanceBands - Long, 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.

getComputeConfidenceEnvelope

public String getComputeConfidenceEnvelope()

Returns the Compute Confidence Envelope parameter of this tool . This parameter is String, the confidence envelope is calculated by randomly placing points in the study area. The number of points 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. This is an optional parameter.

Returns:

the Compute Confidence Envelope

setComputeConfidenceEnvelope

public void setComputeConfidenceEnvelope(String computeConfidenceEnvelope)

Sets the Compute Confidence Envelope parameter of this tool . This parameter is String, the confidence envelope is calculated by randomly placing points in the study area. The number of points 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. This is an optional parameter.

Parameters:

computeConfidenceEnvelope - String, the confidence envelope is calculated by randomly placing points in the study area. The number of points 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.

getDisplayResultsGraphically

public String getDisplayResultsGraphically()

Returns the Display Results Graphically parameter of this tool . This parameter is String, specifies whether the tool will display the results of the Multi-Distance Spatial Cluster Analysis tool graphically. This is an optional parameter.

Returns:

the Display Results Graphically

setDisplayResultsGraphically

public void setDisplayResultsGraphically(String displayResultsGraphically)

Sets the Display Results Graphically parameter of this tool . This parameter is String, specifies whether the tool will display the results of the Multi-Distance Spatial Cluster Analysis tool graphically. This is an optional parameter.

Parameters:

displayResultsGraphically - String, specifies whether the tool will display the results of the Multi-Distance Spatial Cluster Analysis tool graphically.

getWeightField

public Object getWeightField()

Returns the Weight Field parameter of this tool . This parameter is Field, a numeric field with weights that give certain features more influence than others. This is an optional parameter.

Returns:

the Weight Field

setWeightField

public void setWeightField(Object weightField)

Sets the Weight Field parameter of this tool . This parameter is Field, a numeric field with weights that give certain features more influence than others. This is an optional parameter.

Parameters:

weightField - Field, a numeric field with weights that give certain features more influence than others.

getBeginningDistance

public double getBeginningDistance()

Returns the Beginning Distance parameter of this tool . This parameter is Double, 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. This is an optional parameter.

Returns:

the Beginning Distance

setBeginningDistance

public void setBeginningDistance(double beginningDistance)

Sets the Beginning Distance parameter of this tool . This parameter is Double, 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. This is an optional parameter.

Parameters:

beginningDistance - Double, 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.

getDistanceIncrement

public double getDistanceIncrement()

Returns the Distance Increment parameter of this tool . This parameter is Long, 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. This is an optional parameter.

Returns:

the Distance Increment

setDistanceIncrement

public void setDistanceIncrement(double distanceIncrement)

Sets the Distance Increment parameter of this tool . This parameter is Long, 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. This is an optional parameter.

Parameters:

distanceIncrement - Long, 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.

getBoundaryCorrectionMethod

public String getBoundaryCorrectionMethod()

Returns the Boundary Correction Method parameter of this tool . This parameter is String, method to use to correct for under estimates in the number of neighbors for features near the edges of the study area. This is an optional parameter.

Returns:

the Boundary Correction Method

setBoundaryCorrectionMethod

public void setBoundaryCorrectionMethod(String boundaryCorrectionMethod)

Sets the Boundary Correction Method parameter of this tool . This parameter is String, method to use to correct for under estimates in the number of neighbors for features near the edges of the study area. This is an optional parameter.

Parameters:

boundaryCorrectionMethod - String, method to use to correct for under estimates in the number of neighbors for features near the edges of the study area.

getStudyAreaMethod

public String getStudyAreaMethod()

Returns the Study Area Method parameter of this tool . This parameter is String, 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. This is an optional parameter.

Returns:

the Study Area Method

setStudyAreaMethod

public void setStudyAreaMethod(String studyAreaMethod)

Sets the Study Area Method parameter of this tool . This parameter is String, 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. This is an optional parameter.

Parameters:

studyAreaMethod - String, 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.

getStudyAreaFeatureClass

public Object getStudyAreaFeatureClass()

Returns the Study Area Feature Class parameter of this tool . This parameter is Feature Class, 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 specified in the Study Area Feature Class parameter. This is an optional parameter.

Returns:

the Study Area Feature Class

setStudyAreaFeatureClass

public void setStudyAreaFeatureClass(Object studyAreaFeatureClass)

Sets the Study Area Feature Class parameter of this tool . This parameter is Feature Class, 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 specified in the Study Area Feature Class parameter. This is an optional parameter.

Parameters:

studyAreaFeatureClass - Feature Class, 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 specified in the Study Area Feature Class parameter.

getToolName

public String getToolName()

Returns the name of this tool.

Returns:

the tool name

getToolboxName

public String getToolboxName()

Returns the name of the tool box containing this tool.

Returns:

the tool box name

getToolboxAlias

public String getToolboxAlias()

Returns the alias of the tool box containing this tool.

Returns:

the tool box alias