| Label | Explanation | Data Type |
Input Features | The point tracks in which dwells will be found. The input must be a time-enabled layer with features that represent instants in time. | Feature Layer |
Output Dataset
| The output feature class with the resulting dwells. | Feature Class |
Track Fields
| One or more fields that will be used to identify unique tracks. | Field |
Distance Method
| Specifies how the distances between dwell features will be calculated.
| String |
Distance Tolerance | The maximum distance between points to be considered a single dwell location. | Linear Unit |
Time Tolerance | The minimum time duration to be considered a single dwell location. Both time and distance are considered when finding dwells. The Distance Tolerance parameter specifies distance. | Time Unit |
Output Type
| Specifies how the dwell features will be output.
| String |
Summary Statistics
(Optional) | The statistics that will be calculated on specified fields.
| Value Table |
Time Boundary Split
(Optional) |
A time span to split the input data into for analysis. A time boundary allows you to analyze values within a defined time span. For example, if you use a time boundary of 1 day, and set the time boundary reference to January 1, 1980, tracks will be split at the beginning of every day. | Time Unit |
Time Boundary Reference
(Optional) |
The reference time used to split the input data into for analysis. Time boundaries will be created for the entire span of the data, and the reference time does not need to occur at the start. If no reference time is specified, January 1, 1970, is used. | Date |
Summary
Finds locations where moving objects have stopped, or dwelled, using given time and distance thresholds.
Illustration
Usage
The input layer must be time-enabled point features that represent an instant in time.
Dwell locations are defined as sequential observations with little or no movement over a certain period of time. Depending on the field of application, this may be referred to as stay points or idle detection.
The following table lists terminology used in the Find Dwell Locations tool:
Term Description Dwell location
Features representing when a track has been stationary given specified time and distance parameters. This is the output result from the tool that represents dwell features as either points, convex hulls, or mean centers.
Track
A sequence of features that are time enabled with time type instant. Features are determined to be in the sequence by a track identifier field and are ordered by time. For example, a city could have a fleet of snow plow trucks that record their location every 10 minutes. The vehicle ID could represent the distinct tracks.
Observation
A point in a track.
Geodesic
A line drawn on a sphere. A geodesic line drawn on the globe represents the curvature of the earth's geoid.
Planar
A straight-line distance as measured on a flat surface (that is, a Cartesian plane). This is also referred to as Euclidean distance.
Instant
A single moment in time represented by a start time and no end time.
Interval
A duration of time represented by a start time and an end time.
Results are point features representing instants in time, or area features representing an interval in time. The start and end of the interval are determined by the time of the first and last features in a dwell.
Any features that do not have time will be excluded from the analysis.
Dwell locations can only be detected in tracks with more than one feature.
Dwell locations are determined using both time (Time Tolerance parameter) and distance (Distance Tolerance parameter) values. First, the tool assigns features to a track using a unique identifier. Track order is determined by the time of the features. Then the distance between the first observation in a track and the next is calculated. Features are considered to be part of a dwell if two temporally consecutive points stay within the given distance for at least the given duration. When two features are found to be part of a dwell, the first feature in the dwell is used as a reference point, and the tool finds consecutive features that are within the specified distance of the reference point in the dwell. Once all features within the specified distance are found, the tool collects the dwell features and calculates their mean center. Features before and after the current dwell are added to the dwell if they are within the given distance of the dwell location's mean center. This process continues until the end of the track.
You can specify one or more fields to identify tracks. Tracks are represented by the unique combination of one or more track fields.
By default, dwell locations are created using a geodesic method for distance calculation. It is recommended that you use geodesic distance in the following circumstances:
- Tracks cross the international date line—When using the geodesic method, input layers that cross the international date line will have tracks that correctly cross the international date line. This is the default. The input layer or processing spatial reference must be set to a spatial reference that supports wrapping around the international date line, for example, a global projection such as World Cylindrical Equal Area.
- The dataset is not in a local projection—If the input data is in a local projection, use the planar distance method. For example, use the planar method to examine dwell locations in a single state. The input layer or processing spatial reference must be set to a spatial reference local to the dataset.
Output dwell locations can be represented in four ways. The following table shows an example of each:
Output Type parameter option Description Example All features
Every feature is returned. The resulting features have time type instant.
Features that belong to a dwell are rendered in blue. Features that do not belong to a dwell are rendered in gray.
Only a count statistic is calculated for this output type. The count represents the number of features that belong to a single dwell. Features that do not belong to a dwell will have a count of 0.
Dwell features
Only features that are part of a dwell are returned. The resulting features have time type instant.
Only a count statistic is calculated for this output type. The count represents the number of features that belong to a single dwell.
Mean centers
Each dwell has a single point returned representing the mean center of the dwell in distance and time. The resulting features have time type interval.
The count of features in the dwell is always calculated. You can optionally calculate statistics on this type of dwell feature. By default, no statistics are calculated.
Convex hulls
Each dwell is represented by a convex hull of the dwell features. The resulting features have time type interval.
The count of features in the dwell is always calculated. You can optionally calculate statistics on this type of dwell feature. By default, no statistics are calculated.
In addition to the fields from the input layer, the following fields are included in all output features:
Field name Description count
The number of features that were in the dwell
dwellid
A unique ID for the dwell to which the feature belongs
meanx
The mean value of the x-coordinates that compose the dwell
meany
The mean value of the y-coordinates that compose the dwell
meandistance
The average distance between consecutive points in a dwell location
dwellduration
The duration of time, in milliseconds, between the first and last observation included in the dwell location
date
The time of the individual feature created when the output type is dwell features, mean centers, or all features
start_date
The start time created when the output type is convex hulls
end_date
The end time created when the output type is convex hulls
If the output type is All features, the results that belong to a dwell will have the fields described above calculated. The results that do not belong to a dwell will return a value of 0 for the count field, the date field will return the time value of the input feature, and all other fields will return a value of null.
Split tracks using the Time Boundary Split parameter. These segments track at a defined interval. For example, if you set the Time Boundary Reference parameter to 1 day, starting at 9:00 a.m. on January 1, 1990, each track will be truncated at 9:00 a.m. every day. This split accelerates computing time, as it creates smaller tracks for analysis. If splitting by a recurring time boundary makes sense for the analysis, it is recommended for big data processing.
When calculating the convex hull and a dwell location is completely stationary (one unique location) or composed of two unique points, a small value based on the tolerance of the spatial reference used in an analysis will be used as the width, height, or diameter to create output polygons instead of convex hulls. These polygons are used for visualization and do not represent the spatial extent of the dwell. Examples of these cases are described in the following table:
Input case Description Example Coincident (one spatially-unique point)
If the input features are stacked (coincident), the resulting convex hull will be an invalid polygon.
In this example, the coincident input features are represented by the red dot in the center of the yellow polygon. The yellow polygon represents the output convex hull result for coincident points. The blue polygon represents what a true convex hull looks like when there are four noncoincident points in a single dwell location.
Colinear (two spatially-unique points)
If the input features are in a line (most common with two spatially-unique points), the resulting convex hull will be an invalid polygon.
In this example, colinear points are represented by red dots in the yellow polygon. The yellow polygon represents the output convex hull result for colinear points.
When choosing parameters to calculate dwell locations, consider the type of observation and the scale of dwell that you want to find. The following are examples of how you can modify parameters to find dwells in movement data:
- Ship features have vesselID and tripID fields.
- Use the vesselID and tripID fields as the identifiers to calculate dwell locations along distinct routes.
- Use a time tolerance of 1 hour and a distance tolerance of 1 nautical mile to discover where vessels stay within 1 nautical mile for at least 1 hour.
- Animal trackers have animalID fields.
- Use the animalID field as the identifier to compare dwell locations of specific animals.
- To determine the range of an animal, use a time tolerance of 3 days, and a distance tolerance of 10 miles to discover animal habitats of interest.
- For a smaller area of interest, use a time tolerance of 2 hours, and a distance tolerance of 100 meters.
- Ship features have vesselID and tripID fields.
You can improve the performance of the Find Dwell Locations tool by doing one or more of the following:
- Set the extent environment so you only analyze data of interest.
- Output results as Dwell features or Mean centers values.
- Subdivide tracks as much as possible by adding Track Field inputs.
- Use the planar method for distance calculation instead of geodesic.
- Split the tracks using the Time Boundary Split parameter.
- 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.
Parameters
arcpy.gapro.FindDwellLocations(input_features, output, track_fields, distance_method, distance_tolerance, time_tolerance, output_type, {summary_statistics}, {time_boundary_split}, {time_boundary_reference})| Name | Explanation | Data Type |
input_features | The point tracks in which dwells will be found. The input must be a time-enabled layer with features that represent instants in time. | Feature Layer |
output | The output feature class with the resulting dwells. | Feature Class |
track_fields [track_fields,...] | One or more fields that will be used to identify unique tracks. | Field |
distance_method | Specifies how the distances between dwell features will be calculated.
| String |
distance_tolerance | The maximum distance between points to be considered a single dwell location. | Linear Unit |
time_tolerance | The minimum time duration to be considered a single dwell location. Both time and distance are considered when finding dwells. The Distance Tolerance parameter specifies distance. | Time Unit |
output_type | Specifies how the dwell features will be output.
| String |
summary_statistics [summary_statistics,...] (Optional) | The statistics that will be calculated on specified fields.
| Value Table |
time_boundary_split (Optional) |
A time span to split the input data into for analysis. A time boundary allows you to analyze values within a defined time span. For example, if you use a time boundary of 1 day, and set the time boundary reference to January 1, 1980, tracks will be split at the beginning of every day. | Time Unit |
time_boundary_reference (Optional) |
The reference time used to split the input data into for analysis. Time boundaries will be created for the entire span of the data, and the reference time does not need to occur at the start. If no reference time is specified, January 1, 1970, is used. | Date |
Code sample
The following stand-alone script demonstrates how to use the FindDwellLocations function.
# Name: FindDwellLocations.py
# Description: Find the mean centers representing locations where ships have
# stayed within 1 mile across 4 hours of travel.
# Requirements: ArcGIS GeoAnalytics Desktop tools
# Import system modules
import arcpy
# 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\MyAtlanticShips.lyrx'
# MakeFeatureLayer converts the .lyrx to features
myAtlanticShipsInputLayer = arcpy.management.MakeFeatureLayer(inputLyrx, "MyAtlanticShips_layer")
# ApplySymbologyFromLayer sets the time using the .lyrx file definition
arcpy.management.ApplySymbologyFromLayer(myAtlanticShipsInputLayer, inputLyrx)
# Set local variables
outFeatures = "c:/mydata/OutputDatasets/AtlanticShips_DwellLocations.shp"
trackIdentifier = "SHIPID"
distance = "1 Miles"
timeDuration = "4 Hours"
outputType = "MEAN_CENTERS"
statistics = [["SPEED", "MEAN"]]
# Run Find Dwell Locations
arcpy.gapro.FindDwellLocations(myAtlanticShipsInputLayer, outFeatures, trackIdentifier,
"GEODESIC", distance, timeDuration,
outputType, statistics)Environments
Licensing information
- Basic: No
- Standard: No
- Advanced: Yes