Assess Sensitivity to Attribute Uncertainty (Spatial Statistics)

Summary

Measures the stability of an analysis result by comparing the original analysis output to the results from multiple tool runs using simulated data. The simulated data accounts for uncertainty in one or more analysis variables. Three types of attribute uncertainty are supported: margin of error, confidence bounds, and a percentage of the original attribute value.

Learn more about how Assess Sensitivity to Attribute Uncertainty Works

Illustration

Usage

• The Analysis Result Features parameter requires analysis results from one of the following tools in the Spatial Statistics toolbox:

  • Hot Spot Analysis (Getis-Ord Gi*)
  • Cluster and Outlier Analysis (Anselin Local Moran's I)
  • Optimized Hot Spot Analysis
  • Optimized Outlier Analysis
  • Generalized Linear Regression
  • Spatial Autocorrelation (Global Moran's I)

• The tool produces an output group layer with layers, charts, and pop-ups that compare how the original analysis differs across simulated runs.

• The outputs of the tool depend on the type of analysis that is being assessed.

  • For Hot Spot Analysis, Optimized Hot Spot Analysis, Cluster and Outlier Analysis, and Optimized Outlier Analysis, the tool provides a copy of the original analysis outputs and a layer that highlights the locations that produced a different result from the original analysis for at least 80 percent of the simulated runs.
  • For Generalized Linear Regression, the tool provides a copy of the original analysis outputs and a table containing the results of each simulation. The table includes charts to visualize the regression results (distribution of R-squared, Jarque-Bera, and coefficients) across simulated runs.
  • For Spatial Autocorrelation (Global Moran's I), the tool provides a copy of the analysis input features and a table containing the results of each simulation. The table includes charts to visualize the Z-score and Global Moran's I results across simulated runs.

• The simulations that the tool will run are configured using the following parameters:

  • Uncertainty Type—Specifies how the uncertainty of the attributes will be measured and the range of possible uncertainty for the simulated data. For example, a margin of error field can be used to denote the uncertainty in the analysis variable values.
  • Simulation Method—Specifies the way that the simulated data will be generated using different statistical distributions. For example, the Normal option for the Simulation Method parameter will generate simulated values using a normal distribution. The original attribute value will be the mean and the Uncertainty Type parameter (the margin of error) determines the standard deviation.

  

  The normal simulation method generates simulated values using a normal distribution. If Uncertainty Type is Margin of Error, the mean of the distribution is the original attribute value and the standard deviation is the margin of error.

• The Simulation Data Limits parameter allows you to further configure the simulations. Use this parameter to prevent the simulations from generating data that would not make sense in the analysis, for example negative values when the analysis variable is the percentage of the population below the poverty line.

• The tool reads the metadata of the Analysis Result Features parameter value to identify the analysis tool that produced the layer. If multiple tools were run on the layer, the most recent tool will be used.

Parameters

Dialog

Label	Explanation	Data Type
Analysis Result Features	A feature class containing the output analysis result from a spatial statistics tool. Only certain tools are supported. This is the analysis result that will be evaluated for stability.	Feature Layer
Output Features	The output features that will contain a copy of the original analysis results and fields summarizing the stability of the analysis for each feature.	Feature Class
Output Simulation Table	The output table that will contain fields summarizing the stability of the analysis.	Table
Analysis Input Features (Optional)	The input features that were used in the analysis that produced the analysis result features.	Feature Layer
Uncertainty Type (Optional)	Specifies how attribute uncertainty will be measured. Margin of error—The input feature class of the original analysis contains a field, with the symmetrical margin of error for each feature, that will be used. Upper and lower bounds—The input feature class of the original analysis contains a field, with the lower bound and upper bound for each feature, that will be used. The bounds may be asymmetric with respect to a feature's analysis variable value. Percent above and below—The analysis variable will be adjusted by the percentage specified by the Percentage Below and Above Values parameter.	String
Margin of Error Field (Optional)	The field containing the margin of error (MOE) of the analysis variable. The MOE is used to construct a symmetric distribution from which the simulated values will be generated.	Value Table
Lower and Upper Bounds Field (Optional)	The fields containing the lower and upper bounds for the analysis variable. Values will be generated between the lower and upper confidence bounds.	Value Table
Percentage Below and Above Values (Optional)	The percentage of the original attribute value that will be subtracted and added to the original value of the analysis variable to create a range of values for the simulations.	Value Table
Number of Simulations (Optional)	The number of simulations that will be performed.	Long
Simulation Method (Optional)	Specifies the probability distribution that will be used to simulate data. Normal—A normal distribution will be used. This is the default. Uniform—A uniform distribution will be used. Triangular—A triangular distribution will be used.	String
Workspace for Simulation Results (Optional)	An existing workspace where the analysis results from each simulation will be stored. The workspace can be a folder or a geodatabase.	Workspace
Simulation Data Limits (Optional)	The lower and upper limits for the simulated values. All simulated values will be within these limits. For example, for counts or percentages, use a lower limit of zero to ensure that there are no negative counts or percentages.	Value Table
Margin of Error Confidence Level (Optional)	The confidence level of the margins of error. For example, if the margins of error were created from 95 percent confidence intervals, provide a value of 95.	Long

Derived Output

Label	Explanation	Data Type
Output Group Layer	A group layer of the outputs.	Group Layer
Workspace for Simulation Results	A workspace where the analysis results from each simulation are stored. The workspace can be a folder or a geodatabase.	Workspace

Python

arcpy.stats.AttributeUncertainty(in_features, out_features, out_simulation_table, {analysis_input_features}, {uncertainty_measure}, {moe_field}, {confidence_bound_field}, {randomize_pct}, {num_simulations}, {simulation_method}, {output_workspace}, {sim_data_limits}, {moe_conf_level})

Name	Explanation	Data Type
in_features	A feature class containing the output analysis result from a spatial statistics tool. Only certain tools are supported. This is the analysis result that will be evaluated for stability.	Feature Layer
out_features	The output features that will contain a copy of the original analysis results and fields summarizing the stability of the analysis for each feature.	Feature Class
out_simulation_table	The output table that will contain fields summarizing the stability of the analysis.	Table
analysis_input_features (Optional)	The input features that were used in the analysis that produced the analysis result features.	Feature Layer
uncertainty_measure (Optional)	Specifies how attribute uncertainty will be measured. MOE—The input feature class of the original analysis contains a field with the symmetrical margin of error for each feature and that will be used. CONFIDENCE_BOUNDS—The input feature class of the original analysis contains a field with the lower bounds and upper bounds for each feature and that will be used. The bounds may be asymmetric with respect to a feature's analysis variable value. PERCENTAGE—The analysis variable will be adjusted by the percentage specified by the randomize_pct parameter.	String
moe_field [moe_field,...] (Optional)	The field containing the margin of error (MOE) of the analysis variable. The MOE is used to construct a symmetric distribution from which the simulated values will be generated.	Value Table
confidence_bound_field [confidence_bound_field,...] (Optional)	The fields containing the lower and upper bounds for the analysis variable. Values will be generated between the lower and upper confidence bounds.	Value Table
randomize_pct [randomize_pct,...] (Optional)	The percentage of the original attribute value that will be subtracted and added to the original value of the analysis variable to create a range of values for the simulations.	Value Table
num_simulations (Optional)	The number of simulations that will be performed.	Long
simulation_method (Optional)	Specifies the probability distribution that will be used to simulate data. NORMAL—A normal distribution will be used. This is the default. UNIFORM—A uniform distribution will be used. TRIANGULAR—A triangular distribution will be used.	String
output_workspace (Optional)	An existing workspace where the analysis results from each simulation will be stored. The workspace can be a folder or a geodatabase.	Workspace
sim_data_limits [sim_data_limits,...] (Optional)	The lower and upper limits for the simulated values. All simulated values will be within these limits. For example, for counts or percentages, use a lower limit of zero to ensure that there are no negative counts or percentages.	Value Table
moe_conf_level (Optional)	The confidence level of the margins of error. For example, if the margins of error were created from 95 percent confidence intervals, provide a value of 95.	Long

Derived Output

Name	Explanation	Data Type
out_group_layer	A group layer of the outputs.	Group Layer
out_workspace	A workspace where the analysis results from each simulation are stored. The workspace can be a folder or a geodatabase.	Workspace

Code sample

AttributeUncertainty example 1 (Python window)

The following Python script demonstrates how to use the AttributeUncertainty function:

import arcpy

in_features = r"C:\US_poverty.gdb\hot_spot_analysis_results"
out_features = r"C:\US_poverty.gdb\uncertainty_pop_below_poverty_line"
analysis_input_features = r"C:\US_poverty.gdb\poverty_prevalence_us_counties"
uncertainty_measure = "PERCENTAGE"
randomize_pct = "pop_below_poverty_line 5 10",
num_simulations = 30
simulation_method = "UNIFORM"
sim_data_limits = "pop_below_poverty_line 0 #"

arcpy.stats.AttributeUncertainty(
    in_features, out_features, None, analysis_input_features, uncertainty_measure, 
    None, None, randomize_pct, num_simulations, simulation_method, None, sim_data_limits)

AttributeUncertainty example 2 (stand-alone script)

The following Python script demonstrates how to use the AttributeUncertainty function:

# Analyze the stability of a hot spot analysis 

import arcpy 

arcpy.env.workspace = r"C:\US_poverty.gdb"

try: 
				# Run the Hot Spot Analysis (Local Gi*) tool to analyze the spatial distribution of U.S. residents living below the poverty line
    arcpy.stats.HotSpots(
        Input_Feature_Class="poverty_prevalence_us_counties",
        Input_Field="pop_below_poverty_line",
        Output_Feature_Class="hot_spot_analysis_results",
        Conceptualization_of_Spatial_Relationships="K_NEAREST_NEIGHBORS",
        number_of_neighbors=30)

					# Run the Attribute Uncertainty tool with a percentage uncertainty
					arcpy.stats.AttributeUncertainty(
    					in_features="hot_spot_analysis_results",
    					out_features="uncertainty_pop_below_poverty_line",
    					analysis_input_features= "poverty_prevalence_us_counties",
    					uncertainty_measure="PERCENTAGE",
    					randomize_pct="pop_below_poverty_line 5 10",
   					 num_simulations=30,
    					simulation_method="UNIFORM",
    					sim_data_limits="pop_below_poverty_line 0 #")

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

Environments

Output Coordinate System, Random number generator