Summary
Calculates a magnitude-per-unit area from point features that fall within a neighborhood around each cell.
Illustration
Usage
-
The Calculate Density tool requires a single input of point features.
-
Density can optionally be calculated using one or more count fields. A count field is a numerical field that specifies the number of incidents at each location. Features such as cities or highways can use a count field when calculating the density of population or lanes of traffic, respectively. If you specify a count field, the density will be calculated for the count field in addition to the density of points.
-
Input points are aggregated into bins for analysis. You must specify the bin size to aggregate data into. By default, output results will be in square kilometers.
-
Input points are aggregated into bins of a specified size and shape (hexagon or square). If you are aggregating into hexagons, the bin size d is the height of each hexagon, and the width of the resulting hexagon will be two times the height divided by the square root of three. If you are aggregating into squares, the bin size d is the height of the square, which is equal to the width.
-
You must specify a neighborhood size that is greater than the bin size. The neighborhood size is used to find input features within the same neighborhood as the feature (bin) of interest.
Larger values of the neighborhood size produce a more generalized density output. Smaller values produce an output that shows more detail.
Only points that fall within a neighborhood are considered when calculating the density. If no points fall within the neighborhood of a particular cell, that cell is not assigned a value.
-
There are two weighting options to calculate density: The Uniform option sums all the values within the neighborhood and divides them by the area. The Kernel option weights values in the neighborhood by distance from the feature of interest and applies a kernel function to fit a smooth tapered surface to each point.
-
Only areas within the neighborhood of a bin containing points will be returned.
If the area unit scale factor units are small relative to the distance between the points, the output values may also be very small. To obtain larger values, use the area unit scale factor for larger units (for example, use Square Kilometers rather than Square Meters).
Calculate Density requires that your area layer be in a projected coordinate system. If your data is not projected and you do not set a projected coordinate system, analysis will be completed in World Cylindrical Equal Area (WKID 54034).
The density values will always be floating point.
-
Calculate Density allows you to optionally analyze using time stepping. Each time step is analyzed independent of features outside the time step. To use time stepping, your input data must be time enabled and represent an instant in time. When time stepping is applied, output features will be time intervals represented by fields.
When input features are analyzed using time steps, each time step is analyzed independent of features outside of the time step.
The Time Step Reference parameter can be a date and time value or solely a date value; it cannot be solely a time value.
The following fields are included in the output features:
Field name Description density
The density of the given polygon. This is returned in the specified unit scale factor.
density_<fieldname>
The density weighted by the given field. This is only returned when one or more fields are specified.
start_datetime
When time stepping is specified, output polygons will have a time interval. This field represents the start time.
end_datetime
When time stepping is specified, output polygons will have a time interval. This field represents the end time.
You can improve the performance of the Calculate Density tool by using one or more of the following tips:
- Set the extent environment so you only analyze data of interest.
- Larger bins will perform better than smaller bins. If you are unsure about which size to use, start with a larger bin to prototype.
- Similar to bins, larger time steps will perform better than smaller time steps.
- Decrease the ratio of the neighborhood size to the bin size. A neighborhood size that is three times the size of the bin will perform better than one that is 10 times the bin size.
- Use data that is local to where the analysis is being run.
This geoprocessing tool is powered by ArcGIS GeoAnalytics Server. Analysis is completed on your GeoAnalytics Server, and results are stored in your content in ArcGIS Enterprise.
When running GeoAnalytics Server tools, the analysis is completed on the GeoAnalytics Server. For optimal performance, make data available to the GeoAnalytics Server through feature layers hosted on your ArcGIS Enterprise portal or through big data file shares. Data that is not local to your GeoAnalytics Server will be moved to your GeoAnalytics Server before analysis begins. This means that it will take longer to run a tool, and in some cases, moving the data from ArcGIS Pro to your GeoAnalytics Server may fail. The threshold for failure depends on your network speeds, as well as the size and complexity of the data. Therefore, it is recommended that you always share your data or create a big data file share.
Learn more about sharing data to your portal
Learn more about creating a big data file share through Server Manager
Similar analysis can also be completed using the following:
- Aggregate Points in the GeoAnalytics Desktop toolbox or GeoAnalytics Server toolbox
- Point Density tool in the Spatial Analyst toolbox
- Kernel Density tool in the Spatial Analyst toolbox
- Calculate Density tool in the Standard Feature Analysis toolbox
Syntax
arcpy.geoanalytics.CalculateDensity(input_layer, output_name, bin_type, bin_size, weight, neighborhood_size, {fields}, {area_unit_scale_factor}, {time_step_interval}, {time_step_repeat}, {time_step_reference}, {data_store})| Parameter | Explanation | Data Type |
input_layer | The points that will be used to calculate the density. | Feature Set |
output_name | The name of the output feature service. | String |
bin_type | Specifies the bin shape that will be used in the analysis.
| String |
bin_size | The size of the bins used to aggregate input features. When generating bins for squares, the number and units specified determine the height and length of the square. For hexagons, the number and units specified determine the distance between parallel sides. | Linear Unit |
weight | Specifies the weighting to be applied to the density function.
| String |
neighborhood_size | The search radius to be applied to density calculations. | Linear Unit |
fields [fields,...] (Optional) | One or more fields 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 must be numeric. By default, the density of the count of input points will always be calculated. | Field |
area_unit_scale_factor (Optional) | Specifies the area units of the output density values. The default unit is based on the units of the output spatial reference.
| String |
time_step_interval (Optional) | A value that specifies the duration of the time step. This parameter is only available if the input points are time enabled and represent an instant in time. Time stepping can only be applied if time is enabled on the input. | Time Unit |
time_step_repeat (Optional) | A value that specifies how often the time-step interval occurs. This parameter is only available if the input points are time enabled and represent an instant in time. | Time Unit |
time_step_reference (Optional) | A date that specifies the reference time with which to align the time steps. The default is January 1, 1970, at 12:00 a.m. This parameter is only available if the input points are time enabled and represent an instant in time. | Date |
data_store (Optional) | Specifies the ArcGIS Data Store where the output will be saved. The default is SPATIOTEMPORAL_DATA_STORE. All results stored in a spatiotemporal big data store will be stored in WGS84. Results stored in a relational data store will maintain their coordinate system.
| String |
Derived Output
| Name | Explanation | Data Type |
| output | The magnitude-per-unit area from point features that fall within a neighborhood around each cell. | Feature Set |
Code sample
The following Python window script demonstrates how to use the CalculateDensity tool.
#-------------------------------------------------------------------------------
# Name: Calculate Density.py
# Description: Calculate density using the count of points as well as the severity
# value of outbreaks by week.
# Requirements: ArcGIS GeoAnalytics Server
# Import system modules
import arcpy
# Set local variables
# This example used a big data file share name "HealthInfo" with dataset
# "Outbreaks" registered on a GeoAnalytics server
inFeatures = "https://MyGeoAnalyticsMachine.domain.com/geoanalytics/rest/services/DataStoreCatalogs/bigDataFileShares_HealthInfo/BigDataCatalogServer/Outbreaks"
# By default, the count of points will be used in addition to any other fields
# that are specified
fields = "Severity"
# Set the size of bins and neighborhood and the time step size
binSize = "1 Kilometers"
neighborhoodSize = "2 Kilometers"
timeStepInterval = "1 Weeks"
# Specify output info
outFS = "OutbreakDenisty"
dataStore = "SPATIOTEMPORAL_DATA_STORE"
# Execute Calculate Density
arcpy.geoanalytics.CalculateDensity(inFeatures, outFS, 'HEXAGON', binSize,
'UNIFORM', neighborhoodSize, fields,
'SQUARE_KILOMETERS', timeStepInterval, None,
None, dataStore)Environments
- Output Coordinate System
The coordinate system that will be used for analysis. Analysis will be completed in the input coordinate system unless specified by this parameter. For GeoAnalytics Tools, final results will be stored in the spatiotemporal data store in WGS84.
Licensing information
- Basic: Requires ArcGIS GeoAnalytics Server
- Standard: Requires ArcGIS GeoAnalytics Server
- Advanced: Requires ArcGIS GeoAnalytics Server