| Label | Explanation | Data Type |
Input Features
| The point or polygon features that will be used to create the spatial components. | Feature Layer |
Output Features
| The output feature class that will contain the spatial components as fields. The number of fields created depends on the Relative Moran's I Threshold and Maximum Number of Spatial Components parameter values. | Feature Class |
Append All Fields From Input Features
(Optional) | Specifies whether all fields will be copied from the input features to the output feature class.
| Boolean |
Relative Moran's I Threshold
(Optional) | The threshold value for including a spatial component. The value is a proportion of the largest possible Moran's I value for the spatial weights, and a component must have a larger Moran's I value than this threshold to be included. The default is 0.25, meaning that for a component to be included, it must have a Moran's I value that is at least 25 percent of the maximum possible Moran's I value. The value must be between 0 and 1, and smaller values will result in more components. | Double |
Maximum Number of Spatial Components
(Optional) | The maximum number of spatial components that will be created. The default is 15. | Long |
Neighborhood Type
(Optional) | Specifies how neighbors will be chosen for each input feature. Neighboring features must be identified in order to decompose the spatial structure of the input features.
| String |
Distance Band
(Optional) | The distance within which features will be included as neighbors. If no value is provided, one will be estimated during processing and included as a geoprocessing message. If the specified distance results in more than 1,000 neighbors, only the closest 1,000 features will be included as neighbors. | Linear Unit |
Number of Neighbors
(Optional) | The number of neighbors that will be included for each feature. The number does not include the focal feature. The default is 8. | Long |
Weights Matrix File
(Optional) | The path and file name of the spatial weights matrix file (.swm) that defines the neighbors and weights between the input features. | File |
Local Weighting Scheme
(Optional) | Specifies the weighting scheme that will be applied to neighboring features.
| String |
Kernel Bandwidth
(Optional) | The bandwidth of the bisquare or Gaussian local weighting schemes. If no value is provided, one will be estimated during processing and included as a geoprocessing message. | Linear Unit |
Output Spatial Weights Matrix File
(Optional) | The output spatial weights matrix file (.swm) of the neighbors and weights of all pairs of features. If created, this file can be reused in tools that allow defining neighbors and weights with spatial weights matrix files. | File |
Unique ID Field (Optional) | The unique ID field of the output spatial weights matrix file. The field must be an integer and must have a unique value for each input feature. | Field |
Summary
Decomposes a feature class and neighborhood into a set of spatial components. The components represent potential spatial patterns among the features, such as clusters or trends.
The components are returned as fields of the output feature class and represent variables of the input features and neighborhood that have the strongest possible spatial clustering (spatial autocorrelation). The components are called Moran eigenvectors, and each component represents a different spatial pattern that are each independent of each other.
Illustration
Usage
The spatial components created by the tool represent possible spatial patterns for the features and the neighborhood. However, these patterns may not correspond to the patterns of any variable of interest. This tool is provided to visualize the spatial components in maps and enable custom selection procedures for various applications. Other tools in the Spatial Component Utilities (Moran Eigenvectors) toolset also create spatial components but additionally use or select them in common workflows, such as creating explanatory variables of the components (Create Spatial Component Explanatory Variables tool), removing spatial autocorrelation from a field (Filter Spatial Autocorrelation From Field tool), or suggesting an appropriate neighborhood and spatial scale for analysis (Compare Neighborhood Conceptualizations tool). Use caution when performing a custom selection method (such as AIC selection or using the first K components) because it is common to inadvertently select too many components, which can cause overfitting and bias in subsequent analyses. The other tools in the toolset have been designed and validated to prevent overfitting.
The number of spatial components created by the tool depends on the values of the Relative Moran's I Threshold and Maximum Number of Components parameters. The components are ordered from the largest Moran's I value to the smallest, and the tool stops including new components when it reaches the maximum number or when the Moran's I value of the next component is smaller than the threshold. The threshold is provided as a proportion of the Moran's I value of the first component. For example, if the first component has a Moran's I value equal to 0.8 and the threshold value is 0.25, then the next component will only be included if its Moran's I value is at least 0.2 (0.8 x 0.25).
The spatial components will be returned as fields of the output feature class, and when the tool is run in an active map, the output feature layer will draw based on the first component.
The geoprocessing messages include a Spatial Autocorrelation of Spatial Components table that displays the Moran's I value and p-value for each component created by the tool.
Parameters
arcpy.stats.DecomposeSpatialStructure(in_features, out_features, {append_all_fields}, {min_autocorrelation}, {max_components}, {neighborhood_type}, {distance_band}, {number_of_neighbors}, {weights_matrix_file}, {local_weighting_scheme}, {kernel_bandwidth}, {out_swm}, {id_field})| Name | Explanation | Data Type |
in_features | The point or polygon features that will be used to create the spatial components. | Feature Layer |
out_features | The output feature class that will contain the spatial components as fields. The number of fields created depends on the min_autocorrelation and max_components parameter values. | Feature Class |
append_all_fields (Optional) | Specifies whether all fields will be copied from the input features to the output feature class.
| Boolean |
min_autocorrelation (Optional) | The threshold value for including a spatial component. The value is a proportion of the largest possible Moran's I value for the spatial weights, and a component must have a larger Moran's I value than this threshold to be included. The default is 0.25, meaning that for a component to be included, it must have a Moran's I value that is at least 25 percent of the maximum possible Moran's I value. The value must be between 0 and 1, and smaller values will result in more components. | Double |
max_components (Optional) | The maximum number of spatial components that will be created. The default is 15. | Long |
neighborhood_type (Optional) | Specifies how neighbors will be chosen for each input feature. Neighboring features must be identified in order to decompose the spatial structure of the input features.
| String |
distance_band (Optional) | The distance within which features will be included as neighbors. If no value is provided, one will be estimated during processing and included as a geoprocessing message. If the specified distance results in more than 1,000 neighbors, only the closest 1,000 features will be included as neighbors. | Linear Unit |
number_of_neighbors (Optional) | The number of neighbors that will be included for each feature. The number does not include the focal feature. The default is 8. | Long |
weights_matrix_file (Optional) | The path and file name of the spatial weights matrix file (.swm) that defines the neighbors and weights between the input features. | File |
local_weighting_scheme (Optional) | Specifies the weighting scheme that will be applied to neighboring features.
| String |
kernel_bandwidth (Optional) | The bandwidth of the bisquare or Gaussian local weighting schemes. If no value is provided, one will be estimated during processing and included as a geoprocessing message. | Linear Unit |
out_swm (Optional) | The output spatial weights matrix file (.swm) of the neighbors and weights of all pairs of features. If created, this file can be reused in tools that allow defining neighbors and weights with spatial weights matrix files. | File |
id_field (Optional) | The unique ID field of the output spatial weights matrix file. The field must be an integer and must have a unique value for each input feature. | Field |
Code sample
The following Python window script demonstrates how to use the DecomposeSpatialStructure function:
# Extract patterns in the spatial arrangement of the input features.
arcpy.env.workspace = r"c:\data\project_data.gdb"
arcpy.stats.DecomposeSpatialStructure(
in_features="myFeatureClass",
out_features=r"myOutputFeatureClass",
append_all_fields="ALL",
min_autocorrelation=0.25,
max_components=15,
neighborhood_type="CONTIGUITY_EDGES_CORNERS",
distance_band=None,
number_of_neighbors=None,
weights_matrix_file=None,
local_weighting_scheme="",
kernel_bandwidth=None,
out_swm=None,
id_field=None
)The following stand-alone script demonstrates how to use the DecomposeSpatialStructure function:
# Extract patterns in the spatial arrangement of the input features.
import arcpy
# Set the current workspace
arcpy.env.workspace = r"c:\data\project_data.gdb"
# Run the tool
arcpy.stats.DecomposeSpatialStructure(
in_features="myFeatureClass",
out_features=r"myOutputFeatureClass",
append_all_fields="ALL",
min_autocorrelation=0.25,
max_components=15,
neighborhood_type="CONTIGUITY_EDGES_CORNERS",
distance_band=None,
number_of_neighbors=None,
weights_matrix_file=None,
local_weighting_scheme="",
kernel_bandwidth=None,
out_swm=None,
id_field=None
)
# Print the messages.
print(arcpy.GetMessages())