Summary
Measures local patterns of spatial association, or colocation, between two categories of point features using the colocation quotient statistic.
Illustration
Usage
This tool only accepts point features. The categories you want to analyze can be contained in the same or two separate datasets. You can also use two separate datasets to be considered as categories. For example, you may have a point dataset with many types of restaurants that will only be considered as category RESTAURANTS and another point dataset containing many types of crimes that will only be considered as category CRIMES.
The tool will determine, for each feature of the Category of Interest, whether the features of the Neighboring Category are more or less present in its neighborhood compared to the overall spatial distribution of the categories. For example, for each feature of category A, a resulting local colocation quotient (LCLQ) value of 1 means that you are as likely to have category B as a neighbor as you might expect. A LCLQ value greater than 1 means you are more likely (than random) to have B as a neighbor, and a LCLQ value less than 1 means that the feature of category A is less likely to have a category B point as your neighbor (than a random distribution).
Note:
The colocation relationship of this analysis is not symmetric. The colocation quotient values calculated when comparing category A to category B will be different than the colocation quotient values calculated when comparing category B to category A.
Also, if you have category C in your neighborhood, the resulting colocation quotients will be different than if you only had categories A and B. Depending on the question you are asking, it may be important to create a subset of your data to include only categories A and B. However, when creating a subset, you are losing information about the other categories present. Selecting and creating a subset of your data is important in cases in which you are sure that the occurrence of one category is not at all affected by the occurrence of another.
Spatial relationships can be defined using a Distance band, K nearest neighbors, or a spatial weights matrix file through the Neighborhood Type parameter.
You can analyze your data using space time windows by specifying the Time Field of Interest, Time Field of Neighboring Categories, and Temporal Relationship Type parameters. Using space time windows, you can control which features are included in the neighborhood analyzed. Features that are near each other in space and time will be analyzed together because all feature relationships are assessed relative to the location and time stamp of the target feature. You can also specify whether the tool searches for features before or after the target feature, or you can create a time span during which the tool will search for features before and after the target feature being analyzed.
The Number of Permutations parameter is used to calculate p-values. Choosing the number of permutations is a balance between precision and increased processing time. While the default is 99 permutations, it is recommended that you increase the number of permutations for your final analysis results.
A global colocation quotient can also be calculated by specifying a path for the Output Table for Global Relationships parameter. This table contains colocation quotients so you can analyze the measures of spatial association between all categories in your dataset. This allows you to explore other relationships in your data, as you may find other strongly colocated categories globally. If you do find other strongly colocated categories, you can extend your analysis by either exploring the local nature of that relationship by running the tool again with those categories of interest or running the tool again by removing those categories from the analysis if you think the strongly colocated categories are introducing unnecessary bias in your results.
The output of this tool is a map displaying each of the Input Features of Interest symbolized by whether they were significantly colocated with or isolated from the Input Neighboring Features. The tool adds fields to the Output Features including the Local Colocation Quotient calculated, p-value, LCLQ Bin used for symbolization, and the LCLQ Type. An optional Output Table for Global Relationships can be specified that will report the global colocation quotients between all the categories in the Field of Interest and all the categories present in the Field Containing the Neighboring Category.
This tool supports parallel processing and uses 50 percent of available processors by default. The number of processors can be increased or decreased using the Parallel Processing Factor environment.
Syntax
ColocationAnalysis(input_type, in_features_of_interest, output_features, {field_of_interest}, {time_field_of_interest}, {category_of_interest}, {input_feature_for_comparison}, {field_for_comparison}, {time_field_for_comparison}, {category_for_comparison}, neighborhood_type, {number_of_neighbors}, {distance_band}, {weights_matrix_file}, {temporal_relationship_type}, {time_step_interval}, {number_of_permutations}, {local_weighting_scheme}, {output_table})| Parameter | Explanation | Data Type |
input_type | Specifies whether the in_features_of_interest will come from the same dataset with specified categories, different datasets with specified categories, or different datasets that will be treated as their own category (for example, one dataset with all points representing cheetahs and a second dataset in which all points represent gazelles).
| String |
in_features_of_interest | The feature class containing points with representative categories. | Feature Layer |
output_features | The output feature class containing all the in_features with fields representing the local colocation quotient scores and p-values. | Feature Class |
field_of_interest (Optional) | The field containing the category or categories to be analyzed. | Field |
time_field_of_interest (Optional) | A date field with an optional time stamp for each feature to analyze points using a space time window. Features near each other in space and time will be considered neighbors and will be analyzed together. | Field |
category_of_interest (Optional) | The base category for the analysis. The tool will determine, for each category_of_interest, the degree to which the base category is attracted to or colocated with the neighboring_category. | String |
input_feature_for_comparison (Optional) | The input feature class containing the points with the categories that will be compared. | Feature Layer |
field_for_comparison (Optional) | The field from the input_feature_for_comparison containing the category to be compared. | Field |
time_field_for_comparison (Optional) | A date field with a time stamp for each feature to analyze your points using a space time window. Features near each other in space and time will be considered neighbors and will be analyzed together. | Field |
category_for_comparison (Optional) | The neighboring category for the analysis. The tool will determine the degree to which the category_of_interest is attracted to or isolated from the category_for_comparison. | String |
neighborhood_type | Specifies how the spatial relationships among features are defined.
| String |
number_of_neighbors (Optional) | The number of neighbors around each feature that will be used to test for local relationships between categories. If left blank, the default is 8. The provided value should be large enough to detect the relationships between features, but small enough to still identify local patterns. | Long |
distance_band (Optional) | The neighborhood size is a constant or fixed distance for each feature. All features within this distance will be used to test for local relationships between categories. If left empty, the distance used will be the average distance at which each feature has at least eight neighbors. | Linear Unit |
weights_matrix_file (Optional) | The path to a file containing weights that define spatial, and potentially temporal, relationships among features. | File |
temporal_relationship_type (Optional) | Specifies how temporal relationships among features are defined.
| String |
time_step_interval (Optional) | An integer and unit of measurement representing the number of time units composing the time window. | Time Unit |
number_of_permutations (Optional) | This analysis uses permutations to create a reference distribution. Choosing the number of permutations is a balance between precision and increased processing time. Choose your preference of speed versus precision. More robust and precise results take longer to calculate.
| Long |
local_weighting_scheme (Optional) | Specifies the kernel type that will be used to provide the spatial weighting. The kernel defines how each feature is related to other features within its neighborhood.
| String |
output_table (Optional) | When a value is specified for this parameter, a table is produced to show the global colocation quotients between all the categories in the Field of Interest and all the categories in the Field Containing the Neighboring Category. This table can be used in an exploratory manner to help you determine the local categories to analyze. If Datasets without categories is used as the Input Type, global colocation quotients are calculated for each dataset against each other and also against itself. | Table |
Code sample
The following Python window scripts demonstrate how to use the ColocationAnalysis function.
import arcpy
arcpy.env.workspace = r"C:\Analysis"
# Two categories from the same categorical field.
# Find the colocation of elementary schools and middle schools
arcpy.stats.ColocationAnalysis("SINGLE_DATASET", r"Colocation.gdb\Schools",
r"Outputs.gdb\School_Colocation", "Facility_Type", None,
"Elementary", None, None, None, "Middle", "K_NEAREST_NEIGHBORS",
8, None, None, "BEFORE", None, 99, "BISQUARE",
r"Outputs.gdb\Global_School_Colocation")
# Categories from different datasets without categories
# Find the colocation of elementary schools and hospitals
arcpy.stats.ColocationAnalysis("DATASETS_WITHOUT_CATEGORIES", r"Colocation.gdb\Schools",
r"Outputs.gdb\Schools_Hospitals", None, None, '',
r"Colocation.gdb\Hospitals", None, None, '', "DISTANCE_BAND",
None, "30 Kilometers", None, "BEFORE", None, 199, "GAUSSIAN",
None)
# Categories from two datasets
# Find the colocation of elementary schools and hospitals
arcpy.stats.ColocationAnalysis("TWO_DATASETS", r"Colocation.gdb\Schools",
r"Outputs.gdb\Elementary_Hospitals", "Facility_Type", None,
"Elementary", r"Colocation.gdb\Hospitals", None, None, '',
"K_NEAREST_NEIGHBORS", 15, None, None, "BEFORE", None, 499,
"NONE", None)The following stand-alone Python script demonstrates how to use the ColocationAnalysis function.
# Analyze the spatial relationship (colocation) between elementary school locations and hospital locations
# Two categories from the same categorical field.
# Find the colocation of elementary schools and middle schools
intype = "SINGLE_DATASET"
infc_interest = r"Colocation.gdb\Schools"
outfc = r"Outputs.gdb\School_Colocation"
field_interest = "Facility_Type"
time_field = ""
cat_interest = "Elementary"
infc_neigh = ""
field_neigh = ""
time_field_neigh = ""
cat_neigh = "Middle"
neighborhood_type = "K_NEAREST_NEIGHBORS"
num_neighbors = 8
dist_band = ""
swm_file = ""
temporal_type = ""
time_step_interval = ""
num_permutation = 99
weighting_scheme ="BISQUARE"
out_global_tbl = r"Outputs.gdb\Global_School_Colocation"
arcpy.stats.ColocationAnalysis(intype, infc_interest, outfc, field_interest,
time_field, cat_interest, infc_neigh, field_neigh,
time_field_neigh, cat_neigh, neighborhood_type,
num_neighbors, dist_band, swm_file, temporal_type,
time_step_interval num_permutation, weighting_scheme,
out_global_tbl)
# Categories from different datasets without categories
# Find the colocation of schools and hospitals
intype = "DATASETS_WITHOUT_CATEGORIES"
infc_interest = r"Colocation.gdb\Schools"
outfc = r"Outputs.gdb\Schools_Hospitals"
field_interest = ""
time_field = ""
cat_interest = ""
infc_neigh = r"Colocation.gdb\Hospitals"
field_neigh = ""
time_field_neigh = ""
cat_neigh = ""
neighborhood_type = "DISTANCE_BAND"
num_neighbors = ""
dist_band = "30 Kilometers"
swm_file = ""
temporal_type = ""
time_step_interval = ""
num_permutation = 199
weighting_scheme ="GAUSSIAN"
out_global_tbl = ""
arcpy.stats.ColocationAnalysis(intype, infc_interest, outfc, field_interest,
time_field, cat_interest, infc_neigh, field_neigh,
time_field_neigh, cat_neigh, neighborhood_type,
num_neighbors, dist_band, swm_file, temporal_type,
time_step_interval num_permutation, weighting_scheme,
out_global_tbl)
# Categories from two datasets
# Find the colocation of elementary schools and hospitals
intype = "TWO_DATASETS"
infc_interest = r"Colocation.gdb\Schools"
outfc = r"Outputs.gdb\Elementary_Hospitals"
field_interest = "Facility_Type"
time_field = ""
cat_interest = "Elementary"
infc_neigh = r"Colocation.gdb\Hospitals"
field_neigh = ""
time_field_neigh = ""
cat_neigh = ""
neighborhood_type = "K_NEAREST_NEIGHBORS"
num_neighbors = 15
dist_band = ""
swm_file = ""
temporal_type = ""
time_step_interval = ""
num_permutation = 499
weighting_scheme ="NONE"
out_global_tbl = ""
arcpy.stats.ColocationAnalysis(intype, infc_interest, outfc, field_interest,
time_field, cat_interest, infc_neigh, field_neigh,
time_field_neigh, cat_neigh, neighborhood_type,
num_neighbors, dist_band, swm_file, temporal_type,
time_step_interval num_permutation, weighting_scheme,
out_global_tbl)Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes