Calculate Density (GeoAnalytics Desktop)

Summary

Calculates a magnitude-per-unit area from point features that fall within a neighborhood around each cell.

Learn more about how time stepping works

Illustration

Calculate Density tool illustration

Usage

  • The Calculate Density tool requires a single input of point features.

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

    Hexagonal and square bins

  • You must specify a neighborhood size that is greater than the bin size. The neighborhood size will be used to find input features within the same neighborhood as the feature (bin) of interest.

  • Larger neighborhood size values produce a more generalized density output. Smaller values produce an output that shows more detail.

  • Only points that fall within a neighborhood will be considered when calculating the density. If no points fall within the neighborhood of a particular cell, that cell will not be 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).

  • Analysis with binning requires that the input is projected or that the output coordinate system is set to a projected coordinate system. If the data is not in a projected coordinate system and you do not set one, a projection will be used based on the extent of the data you are analyzing.

  • The density values will always be floating point.

  • Calculate Density allows you to analyze using time stepping. Each time step is analyzed independent of features outside the time step. To use time stepping, the 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 nameDescription

    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_date

    When time stepping is specified, output polygons will have a time interval. This field represents the start time.

    end_date

    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 doing one or more of the following:

    • 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 3 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 Spark. Analysis is completed on your desktop machine using multiple cores in parallel. See Considerations for GeoAnalytics Desktop tools to learn more about running analysis.

  • When running GeoAnalytics Desktop tools, the analysis is completed on your desktop machine. For optimal performance, data should be available on your desktop. If you are using a hosted feature layer, it is recommended that you use ArcGIS GeoAnalytics Server. If your data isn't local, it will take longer to run a tool. To use your ArcGIS GeoAnalytics Server to perform analysis, see GeoAnalytics Tools.

  • Similar analysis can also be completed using the following:

Parameters

LabelExplanationData Type
Input layer

The points that will be used to calculate the density.

Feature Layer
Output Feature Class

A new feature class with calculated densities.

Feature Class
Bin Type

Specifies the bin shape that will be used in the analysis.

  • SquareThe bin shape will be square. This is the default.
  • HexagonThe bin shape will be hexagonal.
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 that will be applied to the density function.

  • UniformA magnitude-per-area calculation in which each bin is equally weighted will be used. This is the default.
  • KernelA magnitude-per-area calculation with a smoothing algorithm applied (kernel) that weights bins closer to the points more heavily will be used.
String
Neighborhood Size

The search radius that will be applied to density calculations.

Linear Unit
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 areal units that will be used for the output density values. The default unit is based on the units of the output spatial reference.

  • International AcresThe areal units will be international acres.
  • HectaresThe areal units will be hectares.
  • Square Statute MilesThe areal units will be square statute miles.
  • Square KilometersThe areal units will be square kilometers.
  • Square MetersThe areal units will be square meters.
  • Square International FeetThe areal units will be square international feet.
  • Square International YardsThe areal units will be square international yards.
  • Square US Survey MilesThe areal units will be square US survey miles.
  • Square US Survey FeetThe areal units will be square US survey feet.
  • Square US Survey YardsThe areal units will be square US survey yards.
  • US Survey AcresThe areal units will be US survey acres.
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

arcpy.geoanalytics.CalculateDensity(input_layer, out_feature_class, bin_type, bin_size, weight, neighborhood_size, {fields}, {area_unit_scale_factor}, {time_step_interval}, {time_step_repeat}, {time_step_reference})
NameExplanationData Type
input_layer

The points that will be used to calculate the density.

Feature Layer
out_feature_class

A new feature class with calculated densities.

Feature Class
bin_type

Specifies the bin shape that will be used in the analysis.

  • SQUAREThe bin shape will be square. This is the default.
  • HEXAGONThe bin shape will be hexagonal.
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 that will be applied to the density function.

  • UNIFORMA magnitude-per-area calculation in which each bin is equally weighted will be used. This is the default.
  • KERNELA magnitude-per-area calculation with a smoothing algorithm applied (kernel) that weights bins closer to the points more heavily will be used.
String
neighborhood_size

The search radius that will 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 areal units that will be used for the output density values. The default unit is based on the units of the output spatial reference.

  • ACRESThe areal units will be international acres.
  • HECTARESThe areal units will be hectares.
  • SQUARE_MILESThe areal units will be square statute miles.
  • SQUARE_KILOMETERSThe areal units will be square kilometers.
  • SQUARE_METERSThe areal units will be square meters.
  • SQUARE_FEETThe areal units will be square feet.
  • SQUARE_YARDSThe areal units will be square yards.
  • SQUARE_MILES_USThe areal units will be square US survey miles.
  • SQUARE_FEET_USThe areal units will be square US survey feet.
  • SQUARE_YARDS_USThe areal units will be square US survey yards.
  • ACRES_USThe areal units will be US survey acres.
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

Code sample

CalculateDensity example (stand-alone script)

The following stand-alone script demonstrates how to use the CalculateDensity function.

# Name: CalculateDensity.py
# Description: Calculate density using the count of points as well as the severity 
#              value of outbreaks by week.

# Import system modules
import arcpy

arcpy.env.workspace = "C:/data/HealthInfo.gdb"

# Enable time on the input features using an .lyrx file.
# To create the .lyrx file, add your layer to a map, open the layer properties 
# and enable time. Then right-click the layer and select Share As Layer File.
inputLyrx = r'C:\data\outbreaks.lyrx'

# MakeFeatureLayer converts the .lyrx to features
outbreaksLayer = arcpy.management.MakeFeatureLayer(inputLyrx, "outbreaks_layer")

# ApplySymbologyFromLayer sets the time using the .lyrx file definition
arcpy.management.ApplySymbologyFromLayer(outbreaksLayer, inputLyrx)

# 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
out = "OutbreakDensity"


# Run Calculate Density
arcpy.gapro.CalculateDensity(outbreaksLayer, out, 'HEXAGON', binSize, 
                             'UNIFORM', neighborhoodSize, fields, 
                             'SQUARE_KILOMETERS', timeStepInterval)