Kernel Density (Spatial Analyst)

Summary

Calculates a magnitude-per-unit area from point or polyline features using a kernel function to fit a smoothly tapered surface to each point or polyline. A barrier can be used to alter the influence of a feature while calculating kernel density.

Learn more about how Kernel Density works

Illustration

OutRas = KernelDensity(InPts, None, 30)

Usage

• Very large or very small values in the Population field (population_field in Python) parameter can produce results that may seem non-intuitive. If the mean of the population field is much larger than 1 (for example, as with 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 enter your own 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 (search_radius in Python) parameter 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 for spatial outliers—input points that are very far away from the rest—so they will not make the search radius unreasonably large.

• If the area unit scale factor units are small relative to the features (distance between points or length of line sections, depending on feature type), the output values may be small. To obtain larger values, select the area unit scale factor for larger units (for example, square kilometers versus square meters).

• 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.

• 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	The input features (point or line) for which to calculate the density.	Feature Layer
Population field	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. Values in the population field can be integer or floating point. The options and default behaviors for the field are listed below. Use None if no item or special value will be used and each feature will be counted once. You can use the Shape field if input features contain z-values. Otherwise, the default field is POPULATION. The following conditions may also apply: If there is no POPULATION field, but there is a POPULATIONabcd field, it will be used by default. The 'abcd' can be any valid characters, for example, POPULATION6, POPULATION1974, or POPULATIONROADTYPE. If there is no POPULATION field or POPULATIONabcd field, but there is a POP field, the POP field will be used by default. If there is no POPULATION field, POPULATIONabcd field, or POP field, but there is a POPabcd field, the POPabcd field will be used by default. If there is no POPULATION field, POPULATIONabcd field, POP field, or POPabcd field, NONE will be used by default.	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 (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
Area units (Optional)	Specifies the area units that will be used for the output density values. A default unit is determined based on the linear unit of the output spatial reference. You can change this to the appropriate unit to convert the density output. Values for line density convert the units of both length and area. If no output spatial reference is specified, the output spatial reference will be the same as the input feature class. The default output density units are determined by the linear units of the output spatial reference . If the output linear units are meters, the output area density units will be set to Square kilometers, outputting square kilometers for point features or kilometers per square kilometers for polyline features. If the output linear units are feet, the output area density units will be set to Square miles. If the output units are anything other than feet or meters, the output area density units will be set to Square map units. That is, the output density units will be the square of the linear units of the output spatial reference. For example, if the output linear units are centimeters, the output area density units will be Square map units, which will result in square centimeters. If the output linear units are kilometers, the output area density units will be Square map units, which will result in square kilometers. The available options and their corresponding output density units are the following: Square map units—The square of the linear units of the output spatial reference will be used. Square miles—U.S. miles will be used. Square kilometers—Kilometers will be used. Acres—U.S. acres will be used. Hectares—Hectares will be used. Square yards—U.S. yards will be used. Square feet—U.S. feet will be used. Square inches—U.S. inches will be used. Square meters—Meters will be used. Square centimeters—Centimeters will be used. Square millimeters—Millimeters will be used.	String
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) method 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 (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

KernelDensity(in_features, population_field, {cell_size}, {search_radius}, {area_unit_scale_factor}, {out_cell_values}, {method}, {in_barriers})

Name	Explanation	Data Type
in_features	The input features (point or line) for which to calculate the density.	Feature Layer
population_field	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. Values in the population field can be integer or floating point. The options and default behaviors for the field are listed below. Use None if no item or special value will be used and each feature will be counted once. You can use the Shape field if input features contain z-values. Otherwise, the default field is POPULATION. The following conditions may also apply: If there is no POPULATION field, but there is a POPULATIONabcd field, it will be used by default. The 'abcd' can be any valid characters, for example, POPULATION6, POPULATION1974, or POPULATIONROADTYPE. If there is no POPULATION field or POPULATIONabcd field, but there is a POP field, the POP field will be used by default. If there is no POPULATION field, POPULATIONabcd field, or POP field, but there is a POPabcd field, the POPabcd field will be used by default. If there is no POPULATION field, POPULATIONabcd field, POP field, or POPabcd field, NONE will be used by default.	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 (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
area_unit_scale_factor (Optional)	Specifies the area units that will be used for the output density values. A default unit is determined based on the linear unit of the output spatial reference. You can change this to the appropriate unit to convert the density output. Values for line density convert the units of both length and area. If no output spatial reference is specified, the output spatial reference will be the same as the input feature class. The default output density units are determined by the linear units of the output spatial reference . If the output linear units are meters, the output area density units will be set to Square kilometers, outputting square kilometers for point features or kilometers per square kilometers for polyline features. If the output linear units are feet, the output area density units will be set to Square miles. If the output units are anything other than feet or meters, the output area density units will be set to Square map units. That is, the output density units will be the square of the linear units of the output spatial reference. For example, if the output linear units are centimeters, the output area density units will be Square map units, which will result in square centimeters. If the output linear units are kilometers, the output area density units will be Square map units, which will result in square kilometers. The available options and their corresponding output density units are the following: SQUARE_MAP_UNITS—The square of the linear units of the output spatial reference will be used. SQUARE_MILES—U.S. miles will be used. SQUARE_KILOMETERS—Kilometers will be used. ACRES—U.S. acres will be used. HECTARES—Hectares will be used. SQUARE_YARDS—U.S. yards will be used. SQUARE_FEET—U.S. feet will be used. SQUARE_INCHES—U.S. inches will be used. SQUARE_METERS—Meters will be used. SQUARE_CENTIMETERS—Centimeters will be used. SQUARE_MILLIMETERS—Millimeters will be used.	String
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) method 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 (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

KernelDensity example 1 (Python window)

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

from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outKDens = KernelDensity("rec_sites.shp", "", 45, 1200, "SQUARE_KILOMETERS",
                         "", "GEODESIC")
outKDens.save("C:/sapyexamples/output/KD_out.tif")

KernelDensity example 2 (stand-alone script)

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

# Name: KernelDensity_Ex_02.py
# Description: Calculates the ozone concentration pattern divided by
#              Sierra Nevada Mountain in California
#              based on the point samples using a kernel function to
#              fit a smoothly tapered surface.
# Requirements: Spatial Analyst Extension

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

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

# Set local variables
inFeatures = "ozone_california.shp"
populationField = "OZONE"
cellSize = 60
searchRadius = 2500
inBarriers = "SierraNevada.shp"

# Execute KernelDensity
outKernelDensity = KernelDensity(inFeatures, populationField, cellSize, searchRadius,
                                 "SQUARE_KILOMETERS", "DENSITIES", "PLANAR", inBarriers)

# Save the output 
outKernelDensity.save("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