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
Determines whether features, or the values associated with features, exhibit statistically significant clustering or dispersion over a range of distances.
The Multi-Distance Spatial Cluster Analysis (Ripleys K Function) tool is contained in the Spatial Statistics Tools tool box.
Usage tips:
- Tool output is a table with fields:andcontaining the expected and observed K values, respectively. A field namedcontains the Observed K values minus the Expected K values. If a confidence interval option is specified, two additional fields namedandwill be included in the Output Table as well. These fields contain confidence interval information for each iteration of the tool, as specified by the Number of Distance Bands parameter. The K function will optionally create a graph layer summarizing results.
- 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 value, 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. Additional information about interpretation is found in .
- Enable the Display Results Graphically parameter to create a line graph summarizing tool results. 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 line graph is created as a graph layer; graph layers are temporary and will be deleted when you close ArcMap. If you right-click the graph layer and select Save, the graph can be written to a Graph File. If you save your map document after saving your graph, a link to the graph file will be saved with your .mxd. For more information about graph files, see .
- For line and polygon features, feature centroids are used in distance computations. For multipoints, polylines, or polygons with multiple parts, the centroid is computed using the weighted mean center of all feature parts. The weighting for point features is 1, for line features is length, and for polygon features is area.
- The Weight Field is most appropriately used when it represents the number of incidents or counts.
- When no Weight Field is specified, the largestvalue 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 or tools.
- When no Weight Field is specified, theis 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, for example, the tool will randomly distribute the set of points 99 times for each iteration. After distributing the points 99 times the tool selects, for each distance, the k value that deviated above and below the Expected k value by the greatest amount; 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 the tool evaluates the clustering of feature values in space. On the other hand, when no Weight Field is specified the tool analyzes clustering/dispersion of feature locations.
- Because theis constructed from random permutations, the values defining the confidence envelope will change from one run to the next, even when parameters are identical. If you set a seed value, however, for the geoprocessing environment, repeat analyses will produce consistent results.
- The number of permutations selected for the Compute Confidence Envelope parameter may be loosely translated to confidence levels: 9 for 90%, 99 for 99%, and 999 for 99.9%.
- 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 is required if USER_PROVIDED_STUDY_AREA_FEATURE_CLASS is chosen for the Study Area Method parameter. This option is only available with an ArcInfo license.
- If a Study Area Feature Class is specified, it should have exactly one single part feature (the study area polygon).
- If no Beginning Distance or Distance Increment is specified, then default values are calculated for you based on the extent of the Input Feature Class.
- The K function has an undercount bias for features located near the study area boundary. The Boundary Correction Method parameter provides methods for addressing this bias:
- NONE
- SIMULATE_OUTER_BOUNDARY_VALUES
- REDUCE_ANALYSIS_AREA
- RIPLEY'S_EDGE_CORRECTION_FORMULA
- 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.
- Map layers can be used to define the Input Feature Class. When using a layer with a selection, only the selected features are included in the analysis.
- When 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. See also .
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 - the feature class upon which the analysis will be performed.outputTable - the table to which the results of the analysis will be written.numberOfDistanceBands - 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.
getInputFeatureClass
public Object getInputFeatureClass()
- Returns the Input Feature Class parameter of this tool .
This parameter is 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 the feature class upon which the analysis will be performed.
This is a required parameter.
- Parameters:
inputFeatureClass - 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 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 the table to which the results of the analysis will be written.
This is a required parameter.
- Parameters:
outputTable - 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 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 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 - 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 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.
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 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.
This is an optional parameter.
- Parameters:
computeConfidenceEnvelope - 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.
getDisplayResultsGraphically
public String getDisplayResultsGraphically()
- Returns the Display Results Graphically parameter of this tool .
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 is an optional parameter.
- Parameters:
displayResultsGraphically - null
getWeightField
public Object getWeightField()
- Returns the Weight Field parameter of this tool .
This parameter is a numeric field with weights representing the number of features/events at each location.
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 a numeric field with weights representing the number of features/events at each location.
This is an optional parameter.
- Parameters:
weightField - a numeric field with weights representing the number of features/events at each location.
getBeginningDistance
public double getBeginningDistance()
- Returns the Beginning Distance parameter of this tool .
This parameter is 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 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 - 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 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 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 - 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 method to use to correct for underestimates 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 method to use to correct for underestimates in the number of neighbors for features near the edges of the study area.
This is an optional parameter.
- Parameters:
boundaryCorrectionMethod - method to use to correct for underestimates 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 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 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 - 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 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.
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 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.
This is an optional parameter.
- Parameters:
studyAreaFeatureClass - 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.
getResultImage
public Object getResultImage()
- Returns the Result Image parameter of this tool (Read only).
This is an derived parameter.
- Returns:
- the Result Image
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