Space Time Kernel Density (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Expands kernel density calculations from analyzing the relative position and magnitude of the input features to include other dimensions such as time and depth (elevation). The resulting output identifies the magnitude-per-unit area using the multiple kernel functions to fit a smoothly tapered surface to each input point.

Usage

• You must provide a value for the Elevation Field (elevation_field in Python) parameter or the Time Field (time_field in Python) parameter, or both. While the tool will initially show both as being required, once a value for one of them has been provided, the other becomes optional.

  The kernel functions are defined based on the parameter values provided. When the Elevation Field parameter value is provided, the kernel is extended along the direction (z) axis. When the Time Field parameter value is provided, the kernel is extended along the time (t) axis. When both values are provided, kernels are extended along the z-axis and t-axis.

  If only one of the of these parameter values is provided, the output will be a three-dimensional raster. If both parameter values are provided, the output will be a four-dimensional raster.

• Very large or very small values in the Population Field (population_field in Python) parameter may produce results that seem nonintuitive. 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 provided a custom search radius.

• The Cell Size (cell_size in Python) parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn’t been provided 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 provided, but the Snap Raster environment has been set, the cell size of the snap raster will be used. If nothing is specified, the cell size will be 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.

• The Resultant Values (resultant_values in Python) parameter specifies what the output raster values represent. If Densities (DENSITIES in Python) the is specified, the values represent the kernel density value per unit area for each cell. If Expected Counts (EXPECTED_COUNTS in Python) is specified, the values represent the kernel density per cell area.

• The Planar option in the Method (method in Python) parameter is appropriate if the analysis will 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 will be performed at a regional or large scale (for example, using Web Mercator or a 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 that fall within the neighborhood are considered when calculating density. If no points 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:

  Hu, Y., Wang, F., Guin, C., & Zhu, H. (2018). "A spatio-temporal kernel density estimation framework for predictive crime hotspot mapping and evaluation." Applied geography, 99, 89-97.

  Nakaya, T., & Yano, K. (2010). Visualising crime clusters in a space‐time cube: An exploratory data analysis approach using space time kernel density estimation and scan statistics. Transactions in GIS, 14(3), 223-239.

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

Parameters

Dialog

Label	Explanation	Data Type
Input Point Features	The input point features for which density will be calculated.	Feature Layer
Population Field	The field denoting population values for each feature. The population 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. Use None if no item or special value will be used and each feature will be counted once.	Field
Elevation Field (Optional)	The field denoting elevation values for each feature. Values in the elevation field can be integer or floating point. Use Empty to support 3D kernel density with time. For 3D features, a pseudo field, Shape.Z, will be added to the field list.	Field
Elevation Field Unit (Optional)	The unit of measure that will be used for the input elevation field value. The default is meters. Use the appropriate unit to represent the values in the Elevation Field parameter value. Inch—Inches will be used. Foot—Feet will be used. Yard—Yards will be used. Mile (US)—U.S. miles will be used. Nautical Mile—Nautical miles will be used. Millimeter—Millimeters will be used. Centimeter—Centimeters will be used. Meter—Meters will be used. Kilometers—Kilometers will be used. Decimeter—Decimeters will be used.	String
Time Field (Optional)	The field denoting time values for each feature.	Field
Cell Size (Optional)	The cell size of the multidimensional raster output that will be created. The value can be defined by a numeric value or obtained from an existing raster dataset. If the cell size isn't provided 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 tool usage for details.	Analysis Cell Size
Search Radius (x and y) (Optional)	The search radius on the x,y plane within which density will be calculated. Define the units to be used. For example, to include all features within a 1-mile neighborhood when the units are meters, set the search radius to 1609.344 (1 mile = 1609.344 meters).	Linear Unit
Search Radius (z) (Optional)	The vertical search distance in the z-direction within which density will be calculated. This vertical distance will be used to search for features in the upward and downward directions along the z-axis. Define the units to be used.	Linear Unit
Search Time Window (t) (Optional)	The search range of time within which density will be calculated. Define the units to be used.	Time Unit
Resultant Values (Optional)	Specifies what the values in the output raster represent. Since the output 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. Planar—The planar distance between features will be used. This is the default. Geodesic—The geodesic distance between features will be used.	String
Minimum Elevation (Optional)	The start elevation that will be used for the multidimensional raster output.	Double
Maximum Elevation (Optional)	The end elevation that will be used for the multidimensional raster output.	Double
Elevation Interval (Optional)	The elevation interval between slices in the multidimensional raster output.	Double
Elevation Unit (Optional)	Specifies the unit of elevation interval that will be used for the multidimensional raster output. The default is meter. Inch—Inches will be used. Foot—Feet will be used. Yard—Yards will be used. Mile (US)—U.S. miles will be used. Nautical Mile—Nautical miles will be used. Millimeter—Millimeters will be used. Centimeter—Centimeters will be used. Meter—Meters will be used. Kilometers—Kilometers will be used. Decimeter—Decimeters will be used.	String
Start Time (Optional)	The start time that will be used for the multidimensional raster output.	Date
End Time (Optional)	The end time that will be used for the multidimensional raster output.	Date
Time Interval (Optional)	The time interval between slices in the multidimensional raster output.	Double
Time Interval Unit (Optional)	Specifies the unit of time interval that will be used for the multidimensional raster output. The default is day. Second—The time interval unit will be seconds. Minute—The time interval unit will be minutes. Hour—The time interval unit will be hours. Day—The time interval unit will be days. Week—The time interval unit will be weeks.	String

Return Value

Label	Explanation	Data Type
Output Raster	The output kernel density multidimensional raster dataset in Cloud Raster Format (.crf). Currently, no other output formats are supported. It is always a floating point raster.	Raster

Python

SpaceTimeKernelDensity(in_features, population_field, {elevation_field}, {elevation_field_unit}, {time_field}, {cell_size}, {kernel_search_radius_xy}, {kernel_search_radius_z}, {kernel_search_time_window}, {resultant_values}, {method}, {min_elevation}, {max_elevation}, {elevation_interval}, {elevation_unit}, {start_time}, {end_time}, {time_interval}, {time_interval_unit})

Name	Explanation	Data Type
in_features	The input point features for which density will be calculated.	Feature Layer
population_field	The field denoting population values for each feature. The population 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. Use '' if no item or special value will be used and each feature will be counted once.	Field
elevation_field (Optional)	The field denoting elevation values for each feature. Values in the elevation field can be integer or floating point. Use '' to support 3D kernel density with time. For 3D features, a pseudo field, Shape.Z, will be added to the field list.	Field
elevation_field_unit (Optional)	The unit of measure that will be used for the input elevation field value. The default is meters. Use the appropriate unit to represent the values in the elevation_field parameter value. INCH—Inches will be used. FOOT—Feet will be used. YARD—Yards will be used. MILE_US—U.S. miles will be used. NAUTICAL_MILE—Nautical miles will be used. MILLIMETER—Millimeters will be used. CENTIMETER—Centimeters will be used. METER—Meters will be used. KILOMETER—Kilometers will be used. DECIMETER—Decimeters will be used.	String
time_field (Optional)	The field denoting time values for each feature.	Field
cell_size (Optional)	The cell size of the multidimensional raster output that will be created. The value can be defined by a numeric value or obtained from an existing raster dataset. If the cell size isn't provided 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 tool usage for details.	Analysis Cell Size
kernel_search_radius_xy (Optional)	The search radius on the x,y plane within which density will be calculated. Define the units to be used. For example, to include all features within a 1-mile neighborhood when the units are meters, set the search radius to 1609.344 (1 mile = 1609.344 meters).	Linear Unit
kernel_search_radius_z (Optional)	The vertical search distance in the z-direction within which density will be calculated. This vertical distance will be used to search for features in the upward and downward directions along the z-axis. Define the units to be used.	Linear Unit
kernel_search_time_window (Optional)	The search range of time within which density will be calculated. Define the units to be used.	Time Unit
resultant_values (Optional)	Specifies what the values in the output raster represent. Since the output 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. PLANAR—The planar distance between features will be used. This is the default. GEODESIC—The geodesic distance between features will be used.	String
min_elevation (Optional)	The start elevation that will be used for the multidimensional raster output.	Double
max_elevation (Optional)	The end elevation that will be used for the multidimensional raster output.	Double
elevation_interval (Optional)	The elevation interval between slices in the multidimensional raster output.	Double
elevation_unit (Optional)	Specifies the unit of elevation interval that will be used for the multidimensional raster output. The default is meter. INCH—Inches will be used. FOOT—Feet will be used. YARD—Yards will be used. MILE_US—U.S. miles will be used. NAUTICAL_MILE—Nautical miles will be used. MILLIMETER—Millimeters will be used. CENTIMETER—Centimeters will be used. METER—Meters will be used. KILOMETER—Kilometers will be used. DECIMETER—Decimeters will be used.	String
start_time (Optional)	The start time that will be used for the multidimensional raster output.	Date
end_time (Optional)	The end time that will be used for the multidimensional raster output.	Date
time_interval (Optional)	The time interval between slices in the multidimensional raster output.	Double
time_interval_unit (Optional)	Specifies the unit of time interval that will be used for the multidimensional raster output. The default is day. SECOND—The time interval unit will be seconds. MINUTE—The time interval unit will be minutes. HOUR—The time interval unit will be hours. DAY—The time interval unit will be days. WEEK—The time interval unit will be weeks.	String

Return Value

Name	Explanation	Data Type
out_raster	The output kernel density multidimensional raster dataset in Cloud Raster Format (.crf). Currently, no other output formats are supported. It is always a floating point raster.	Raster

Code sample

SpaceTimeKernelDensity example 1 (Python window)

This example calculates a smoothed temporal kernel density using a shapefile.

from arcpy import env  
from arcpy.sa import * 

env.workspace = "C:/sapyexamples/data" 
STKD_out_raster = SpaceTimeKernelDensity("WOD_subset.shp", "Salinity", "Z", "Meter",
                                         "Time", "0.001", resultant_values="Densities",
                                         method="Planar", elevation_unit="Meter")  

STKD_out_raster.save("C:/sapyexamples/output/STKD_out.crf")

SpaceTimeKernelDensity example 2 (stand-alone script)

This example calculates a smoothed temporal kernel density using a multidimensional dataset.

## Name: SpaceTimeKernelDensity_Ex_standalone.py  
## Description: Calculate spatial temporal salinity concentration using a multidimensional dataset 
## Requirements: Spatial Analyst Extension 
 
## Import system modules 
import arcpy  
from arcpy import env   
from arcpy.sa import *

## Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
 
## Set environment settings 
env.workspace = r" C:\STKD_Test"
# To allow overwriting outputs change overwriteOutput option to True. 
env.overwriteOutput = False 
  
## Set local variables 
in_features = "WOD_subset"  
Population_Field = "Salinity"  
Elevation_Field = "Z"  
Elevation_Field_Unit = "Meter"  
Time_Field = "Time"  
Cell_Size = "30"  
Resultant_values = "Densities"  
Method = "Planar" 
Elevation_Unit = "Meter"  
  
## Execute: Space Time Kernel Density  
STKD_out_raster = SpaceTimeKernelDensity(in_features, Population_Field,   
                                Elevation_Field, Elevation_Field_Unit,   
                                Time_Field, Cell_Size,   
                                resultant_values=Resultant_values,   
                                method=Method, 
                                elevation_unit=Elevation_Unit) 
  
## Save the output 
STKD_out_raster.save("STKD_test.crf")

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

Licensing information

• Basic: Requires Spatial Analyst
• Standard: Requires Spatial Analyst
• Advanced: Requires Spatial Analyst