Calculate Kernel Density Ratio (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Calculates a spatial relative risk surface using two input feature datasets. The numerator in the ratio represents cases, such as number of crimes or number of patients, and the denominator represents the control, such as the total population.

Usage

• This tool uses the same calculations to create density surfaces as the Kernel Density tool. The outputs of the Kernel Density and the Calculate Kernel Density Ratio tools may appear similar; however, the output of the Calculate Kernel Density Ratio tool is normalized, meaning it displays a proportional value. The output of the Kernel Density tool does not. Use a density ratio when the phenomenon being analyzed requires a control, such as total population.

  The individual density surfaces are calculated using the Kernel Density tool before the ratio is calculated.

• Very large or very small values in the population field can produce results that may seem nonintuitive. If the mean of the population field is much larger than 1 (for example, city populations), the default search radius may be very small, resulting in small rings around the input points. If the mean of the population field is much smaller than 1, the calculated search radius may seem unreasonably large. In these cases, you can provide a search radius.

• The Output cell size parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn’t been explicitly specified as the parameter value, it is derived from the Cell Size environment if it has been specified. If the parameter cell size or the environment cell size have not been specified, but the Snap Raster environment has been set, the cell size of the snap raster is used. If nothing is specified, the cell size is calculated from the shorter of the width or height of the extent divided by 250 in which the extent is in the output coordinate system specified in the environment.

• If the cell size is specified using a numeric value, the tool will use it directly for the output raster.

  If the cell size is specified using a raster dataset, the parameter will show the path of the raster dataset instead of the cell size value. The cell size of that raster dataset will be used directly in the analysis, provided the spatial reference of the dataset is the same as the output spatial reference. If the spatial reference of the dataset is different than the output spatial reference, it will be projected based on the specified Cell Size Projection Method value.

• Larger values of the search radius produce a smoother, more generalized density raster. Smaller values produce a raster that shows more detail.

• The default search radius is calculated based on the spatial configuration and number of input points. This approach corrects spatial outliers—input points that are very far away from the rest—so they will not make the search radius unreasonably large.

• The Output cell values (out_cell_values in Python) parameter specifies what the output raster values represent. If Densities is chosen, the values represent the kernel density value per unit area for each cell. If Expected counts is chosen, the values represent the kernel density per cell area. The equation that calculates the counts from the density values is Count = Density × Area.

• The Planar option in the Method (method in Python) parameter is appropriate if the analysis is to be performed at a local scale with a projection that accurately maintains the correct distance and area. The Geodesic option is appropriate if the analysis is to be performed at a regional or large scale (for example, using Web Mercator or any geographic coordinate system). This method takes into account the curvature of the spheroid and correctly handles data near the poles and the international dateline.

• Only the points or portions of a line that fall within the neighborhood are considered when calculating density. If no points or line sections fall within the neighborhood of a particular cell, that cell is assigned NoData.

• For data formats that support Null values, such as file geodatabase feature classes, a Null value will be ignored when used as input.

• When a feature of Input point or polyline features as denominator (in_features_denominator in Python) is zero, the output result within the search radius of the feature will be NoData.

• The default output coordinate system is based on the Input point or polyline features as numerator (in_features_numerator in Python).

  The default values for the Search radius of numerator (search_radius_numerator in Python) and Search radius of denominator (search_radius_denominator in Python) are based on the linear unit of the output coordinate system of the Input point or polyline features as numerator. If the Output Coordinate System environment setting is used, the Search radius of numerator and Search radius of denominator parameter values will be based on the linear unit of the Output Coordinate System environment setting.

  The default analysis extent is the intersection of the extent of the Input point or polyline features as numerator and Input point or polyline features as denominator values.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

• References:

  Silverman, B. W. Density Estimation for Statistics and Data Analysis. New York: Chapman and Hall, 1986.

Parameters

Dialog

Label	Explanation	Data Type
Input point or polyline features as numerator	The input features (point or line) of the cases for which density will be calculated.	Feature Layer
Input point or polyline features as denominator	The input features (point or line) of the control for which density will be calculated.	Feature Layer
Population field of numerator	The field denoting population values for each feature. The population field is the count or quantity to be spread across the landscape to create a continuous surface. Use OID or FID if no item or special value will be used and each feature will be counted once. Values in the population field can be integer or floating point. You can use the Shape field if input features contain z-values.	Field
Population field of denominator	The field denoting population values for each feature. The population field is the count or quantity to be spread across the landscape to create a continuous surface. Use OID or FID if no item or special value will be used and each feature will be counted once. Values in the population field can be integer or floating point. You can use the Shape field if input features contain z-values.	Field
Output cell size (Optional)	The cell size of the output raster that will be created. This parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn't been explicitly specified as the parameter value, the environment cell size value will be used if specified; otherwise, additional rules will be used to calculate it from the other inputs. See the usage section for more detail.	Analysis Cell Size
Search radius of numerator (Optional)	The search radius within which density will be calculated. Units are based on the linear unit of the projection of the output spatial reference. For example, if the units are meters—to include all features within a one-mile neighborhood—set the search radius equal to 1609.344 (1 mile = 1609.344 meters). The default search radius is computed specifically for the input dataset using a spatial variant of Silverman's Rule of Thumb (Silverman, 1986) that is robust enough for spatial outliers (points that are far away from the rest of the points). See the usage tips for a description of the algorithm.	Double
Search radius of denominator (Optional)	The search radius within which density will be calculated. Units are based on the linear unit of the projection of the output spatial reference. For example, if the units are meters—to include all features within a one-mile neighborhood—set the search radius equal to 1609.344 (1 mile = 1609.344 meters). The default search radius is computed specifically for the input dataset using a spatial variant of Silverman's Rule of Thumb (Silverman, 1986) that is robust enough for spatial outliers (points that are far away from the rest of the points). See the usage tips for a description of the algorithm.	Double
Output cell values (Optional)	Specifies what the values in the output raster represent. Since the cell value is linked to the specified cell size, the resulting raster cannot be resampled to a different cell size. Densities—The output values represent the calculated density value per unit area for each cell. This is the default. Expected counts—The output values represent the calculated density value per cell area.	String
Method (Optional)	Specifies whether the flat earth (planar) or the shortest path on a spheroid (geodesic) distance will be used. The geodesic method only supports points as input features. Planar—The planar distance between features will be used. This is the default. Geodesic—The geodesic distance between features will be used.	String
Input barrier features for numerator (Optional)	The dataset that defines the barriers. The barriers can be a feature layer of polyline or polygon features.	Feature Layer
Input barrier features for denominator (Optional)	The dataset that defines the barriers. The barriers can be a feature layer of polyline or polygon features.	Feature Layer

Return Value

Label	Explanation	Data Type
Output raster	The output kernel density raster. It is always a floating point raster.	Raster

Python

CalculateKernelDensityRatio(in_features_numerator, in_features_denominator, population_field_numerator, population_field_denominator, {cell_size}, {search_radius_numerator}, {search_radius_denominator}, {out_cell_values}, {method}, {in_barriers_numerator}, {in_barriers_denominator})

Name	Explanation	Data Type
in_features_numerator	The input features (point or line) of the cases for which density will be calculated.	Feature Layer
in_features_denominator	The input features (point or line) of the control for which density will be calculated.	Feature Layer
population_field_numerator	The field denoting population values for each feature. The population field is the count or quantity to be spread across the landscape to create a continuous surface. Use OID or FID if no item or special value will be used and each feature will be counted once. Values in the population field can be integer or floating point. You can use the Shape field if input features contain z-values.	Field
population_field_denominator	The field denoting population values for each feature. The population field is the count or quantity to be spread across the landscape to create a continuous surface. Use OID or FID if no item or special value will be used and each feature will be counted once. Values in the population field can be integer or floating point. You can use the Shape field if input features contain z-values.	Field
cell_size (Optional)	The cell size of the output raster that will be created. This parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn't been explicitly specified as the parameter value, the environment cell size value will be used if specified; otherwise, additional rules will be used to calculate it from the other inputs. See the usage section for more detail.	Analysis Cell Size
search_radius_numerator (Optional)	The search radius within which density will be calculated. Units are based on the linear unit of the projection of the output spatial reference. For example, if the units are meters—to include all features within a one-mile neighborhood—set the search radius equal to 1609.344 (1 mile = 1609.344 meters). The default search radius is computed specifically for the input dataset using a spatial variant of Silverman's Rule of Thumb (Silverman, 1986) that is robust enough for spatial outliers (points that are far away from the rest of the points). See the usage tips for a description of the algorithm.	Double
search_radius_denominator (Optional)	The search radius within which density will be calculated. Units are based on the linear unit of the projection of the output spatial reference. For example, if the units are meters—to include all features within a one-mile neighborhood—set the search radius equal to 1609.344 (1 mile = 1609.344 meters). The default search radius is computed specifically for the input dataset using a spatial variant of Silverman's Rule of Thumb (Silverman, 1986) that is robust enough for spatial outliers (points that are far away from the rest of the points). See the usage tips for a description of the algorithm.	Double
out_cell_values (Optional)	Specifies what the values in the output raster represent. DENSITIES—The output values represent the calculated density value per unit area for each cell. This is the default. EXPECTED_COUNTS—The output values represent the calculated density value per cell area. Since the cell value is linked to the specified cell size, the resulting raster cannot be resampled to a different cell size.	String
method (Optional)	Specifies whether the flat earth (planar) or the shortest path on a spheroid (geodesic) distance will be used. PLANAR—The planar distance between features will be used. This is the default. GEODESIC—The geodesic distance between features will be used. The geodesic method only supports points as input features.	String
in_barriers_numerator (Optional)	The dataset that defines the barriers. The barriers can be a feature layer of polyline or polygon features.	Feature Layer
in_barriers_denominator (Optional)	The dataset that defines the barriers. The barriers can be a feature layer of polyline or polygon features.	Feature Layer

Return Value

Name	Explanation	Data Type
out_raster	The output kernel density raster. It is always a floating point raster.	Raster

Code sample

CalculateKernelDensityRatio example 1 (Python window)

This example calculates a smoothed density ratio raster from a point shapefile.

from arcpy import env 
from arcpy.sa import * 
env.workspace = r"C:/sapyexamples/data" 
outKDenRa = CalculateKernelDensityRatio("rec_sites.shp", "rec_sites.shp", "Crime", "POP", 45, 1200, 1200, "", "GEODESIC") 
outKDenRa.save(r"C:/sapyexamples/output/KD_out.tif")

CalculateKernelDensityRatio example 2 (stand-alone script)

This example calculates a smoothed density ratio raster from a point shapefile.

# Name: CalculateKernelDensityRatio_Ex_02.py 
# Description: Calculates the ozone concentration per population of each county out of 
#              Sierra Nevada Mountain in California 
#              based on the two point samples using a kernel function to 
#              fit a smoothly tapered surface of density ratio. 
# Requirements: Spatial Analyst Extension 

# Import system modules 
import arcpy 
from arcpy import env 
from arcpy.sa import * 

# Set environment settings 
env.workspace = r"C:/sapyexamples/data" 

# Set local variables 
inFeatures1 = "ozone_california.shp" 
inFeatures2 = "pop_california.shp" 
populationField1 = "OZONE" 
populationField2 = "POP" 
cellSize = 60 
searchRadius1 = 2500 
searchRadius2 = 500 
inBarriers1 = "SierraNevada.shp" 
inBarriers2 = "county.shp" 

# Execute CalculateKernelDensityRatio 
outKernelDensityRatio = CalculateKernelDensityRatio(inFeatures1, inFeatures2, populationField1, populationField2,
                                                    cellSize, searchRadius1, searchRadius2, "DENSITIES", "PLANAR",
                                                    inBarriers1, inBarriers2) 

# Save the output  
outKernelDensityRatio.save(r"C:/sapyexamples/output/KD_ozone_california.tif")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Scratch Workspace, Snap Raster, Tile Size