Space Time Kernel Density (Spatial Analyst)

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.

Learn more about how Space Time Kernel Density works

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.

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

• The tool generates an output raster in either the NetCDF format or Cloud Raster Format (CRF). The location and name you provide for the output raster determines the format in which it is created. For the Output Raster parameter value, use the .nc extension to create the output in the netCDF format. Use the .crf extension to create an output CRF raster. By default, the tool will output a CRF raster.

• You can create a voxel layer output using the optional Output Voxel Layer parameter. This parameter is only available if the Output Raster parameter value is set to create NetCDF output with the .nc extension. If you attempt to specify a voxel layer output using the .crf extension for a CRF raster in the Output raster parameter, the tool will produce an error message and not run.

• If you run the tool in a local scene with the same horizontal and vertical coordinate systems as the input features, a voxel layer will be added to the scene allowing you to interactively explore the results. A notification appears stating that the coordinate system is unknown if no coordinate system is defined. You can also add the output NetCDF raster as a voxel layer using the Make Multidimensional Voxel Layer tool or the Add Multidimensional Voxel Layer dialog box.

  You can convert the output netCDF raster to a multidimensional raster using the Copy Raster tool. You can also add it to a map as a feature layer or raster layer using the Make NetCDF Feature Layer tool or Make NetCDF Raster Layer tool, respectively.

  The generated voxel layer is a temporary layer that will not persist unless it is saved using the Save To Layer File tool. You can use the Create Voxel Scene Layer Content tool to create a scene layer package (.slpk file) from a voxel layer input.

• 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 provide 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 neither the parameter cell size nor the environment cell size have 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) 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 for 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. This method takes into account the curvature of the spheroid and correctly handles data near the poles and the international dateline.

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

  Härdle, W. K., Müller, M, Sperlich, S., and Werwatz, A. Nonparametric and semiparametric models (Vol. 1). Berlin: Springer, 2004.

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

  Nakaya, T., and Yano, K. "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), 2010, 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)	Specifies 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 no cell size is provided, 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. Provide the value and the appropriate units. 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). By default, the units are based on the linear unit of the output spatial reference.	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. Provide the value and the appropriate units.	Linear Unit
Search Time Window (t) (Optional)	The search range of time within which density will be calculated. Provide the value and the appropriate units.	Time Unit
Resultant Values (Optional)	Specifies what the values in the output raster will represent. Since the output cell value is related to the specified cell size, the resulting raster cannot be resampled to a different cell size. Densities—The output values will represent the calculated density value per unit area for each cell. This is the default. Expected Counts—The output values will 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 minimum (lowest) elevation that will be used for the multidimensional raster output.	Double
Maximum Elevation (Optional)	The maximum (highest) elevation that will be used for the multidimensional raster output.	Double
Elevation Interval (Optional)	The elevation interval between slices in the multidimensional raster output. The value must be greater than zero.	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. The value must be greater than zero.	Double
Time Interval Unit (Optional)	Specifies the unit of the 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
Output Voxel Layer (Optional)	The output voxel layer based on volumetric data stored in the output netCDF raster. This output type can only be created when the Output Raster parameter is set to create a netCDF raster with the .nc extension.	Voxel Layer

Return Value

Label	Explanation	Data Type
Output Raster	The output kernel density multidimensional raster dataset. The file name extension determines the format of the output. Use .crf to create a CRF raster. Use .nc to create a netCDF raster. The default output is a CRF raster. 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}, {out_voxel_layer})

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)	Specifies 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 no cell size is provided, 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. Provide the value and the appropriate units. 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). By default, the units are based on the linear unit of the output spatial reference.	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. Provide the value and the appropriate units.	Linear Unit
kernel_search_time_window (Optional)	The search range of time within which density will be calculated. Provide the value and the appropriate units.	Time Unit
resultant_values (Optional)	Specifies what the values in the output raster will represent. Since the output cell value is related to the specified cell size, the resulting raster cannot be resampled to a different cell size. DENSITIES—The output values will represent the calculated density value per unit area for each cell. This is the default. EXPECTED_COUNTS—The output values will 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 minimum (lowest) elevation that will be used for the multidimensional raster output.	Double
max_elevation (Optional)	The maximum (highest) elevation that will be used for the multidimensional raster output.	Double
elevation_interval (Optional)	The elevation interval between slices in the multidimensional raster output. The value must be greater than zero.	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. The value must be greater than zero.	Double
time_interval_unit (Optional)	Specifies the unit of the 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
out_voxel_layer (Optional)	The output voxel layer based on volumetric data stored in the output netCDF raster. This output type can only be created when the out_raster parameter is set to create a netCDF raster with the .nc extension.	Voxel Layer

Return Value

Name	Explanation	Data Type
out_raster	The output kernel density multidimensional raster dataset. The file name extension determines the format of the output. Use .crf to create a CRF raster. Use .nc to create a netCDF raster. The default output is a CRF raster. 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