Find Dwell Locations (GeoAnalytics)

Summary

Finds locations where moving objects have stopped, or dwelled, using given time and distance thresholds.

Illustration

Find Dwell Locations

Usage

  • This geoprocessing tool is available with ArcGIS Enterprise 10.8 or later.

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

    TermDescription

    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 that represent 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) and distance (Distance Tolerance) values. First, the tool assigns features to a track using a unique identifier. Track order is determined by the time of features. Next, 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. Your 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.
    • Your dataset is not in a local projection—If your input data is in a local projection, use the planar distance method. For example, use the planar method to examine dwell locations within a single state. Your input layer or processing spatial reference must be set to a spatial reference local to your dataset.

  • Output dwell locations can be represented in four ways. The following table shows an example of each:

    Output TypeDescriptionExample

    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. Nondwell features will have a count of 0.

    Example of all features returned by the Find Dwell Locations tool

    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.

    Example of dwell features returned by the Find Dwell Locations tool

    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.

    Example of mean center features returned by the Find Dwell Locations tool

    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.

    Example of convex hull features returned by the Find Dwell Locations tool

  • In addition to the fields from the input layer and the specified summary statistics, the following fields are included in all output features:

    Field nameDescription

    count

    The number of features that are 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

    instant_datetime

    The time of the individual feature created when the output type is dwell features, mean center, or all features

    start_datetime

    The start time created when the output type is convex hull

    end_datetime

    The end time created when the output type is convex hull

    If the output type is All Features, the results that belong to a dwell will have the above fields calculated. The results that do not belong to a dwell will return a value of 0 for the count field, the instant_datetime field will return the time value of the input feature, and all other fields will return a value of null.

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

    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 shows what a true convex hull looks like when there are four noncoincident points in a single dwell location.

    Example of coincident features returned when outputting convex hulls

    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 within the yellow polygon. The yellow polygon represents the output convex hull result for colinear points.

    Example of colinear features returned when outputting convex hulls

  • You can split tracks in the following ways:

    • Time Split—Based on a time between inputs. Applying a time split breaks up any track when input data is farther apart than the specified time. For example, if you have five features with the same track identifier and the times of [01:00, 02:00, 03:30, 06:00, 06:30] and set a time split of 2 hours, any features that are measured more than 2 hours apart will be split. In this example, the result would be a track with [01:00, 02:00, 03:30] and [06:00, 06:30], because the difference between 03:30 and 6:00 is greater than 2 hours.
    • Time Boundary Split—Based on defined time intervals. Applying a time boundary split segments tracks at a defined interval. For example, if you set the time boundary 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 your analysis, it is recommended for big data processing.
    • Distance Split—Based on a distance between inputs. Applying a distance split breaks up any track when input data is farther apart than the specified distance. For example, if you set a distance split of 5 kilometers, sequential features greater than 5 kilometers apart will be part of a different track.

  • You can apply none, one, two, or three split options at the same time. The results, assuming you apply a time split of 6 hours, a time boundary of 1 day, and distance split of 16 kilometers, are as follows:

    Five examples of input points (green) with varying time and distance splits
    Five examples of input points (yellow) with varying time and distance splits are shown.

    Split optionDescription

    Six input points with a time and location.

    Input points with the same identifier. The distance between the points is marked on the top of the dotted line, and the time of each point measurement is marked below the points. There are 4 splits on the timeline. The red splits represent the time boundary split of 1 day, starting at 12:00 a.m. The blue split represents the distance split, when the distance between two points is greater than 16 kilometers. The purple split represents the time split, when the temporal distance between two sequential points is greater than 6 hours.

    Example with no time split and no distance split

    Example with no time split and no distance split.

    Example with a time split of 2 hours

    Example with a time split of 2 hours. Any features greater than 2 hours apart are split into separate tracks.

    Example with a time boundary of 1 day

    Example with a time boundary of 1 day, starting at midnight. At each 1-day interval starting from the specified time (here 12:00 a.m.), a track is created.

    Example with a distance split of 16 kilometers

    Example with a distance split of 16 kilometers. Any features greater than 16 kilometers apart (the features at 05:00 a.m. and 06:00 a.m.) are split into separate tracks.

    Example with a time split of 6 hours and a time boundary split of 1 day at 12:00 a.m.

    Example with a time split of 6 hours and a time boundary of 1 day starting at 12:00 a.m. Any features greater than 6 hours apart or that intersect with the time duration split at 12:00 a.m. are split into separate tracks.

    Example with a time split of 6 hours and a distance split of 16 kilometers

    Example with a time split of 6 hours and a distance split of 16 kilometers. Any features greater than 6 hours apart (the features at 06:00 a.m. and 7:00 p.m.) or farther than 16 kilometers apart are split into separate tracks.

    Example with a distance split of 16 kilometers and a time boundary of one day starting at 12:00 a.m.

    Example with a distance split of 16 kilometers and a time boundary of 1 starting at 12:00 a.m. Any features greater than 16 kilometers apart or that intersect with the time duration split at 12:00 a.m. are split into separate tracks.

    Example with a distance split of 16 kilometers, a time split of 6 hours and a time boundary of 1 day starting at 12:00 a.m.

    Example with a distance split of 16 kilometers, a time split of 6 hours, and a time boundary of 1 day starting at 12:00 a.m. Any features greater than 16 kilometers apart, or farther apart than 6 hours, or that intersect with the time duration split at 12:00 a.m. are split into separate tracks.

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

  • 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 center.
    • Subdivide tracks as much as possible by adding Track Field inputs.
    • Use the planar method for distance calculation instead of geodesic.
    • Split your tracks using the Time Split, Time Boundary Split, and Distance Split parameters. Using the Time Boundary Split parameter will provide the biggest performance gain.
    • 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

Syntax

FindDwellLocations(input_features, output_name, track_fields, distance_method, distance_tolerance, time_tolerance, output_type, {summary_statistics}, {data_store}, {time_boundary_split}, {time_boundary_reference})
ParameterExplanationData Type
input_features

The point tracks from which to find dwells. The input must be a time-enabled layer with features that represent instants in time.

Feature Set
output_name

The name of the output feature service.

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

  • GEODESIC If the spatial reference can be panned, tracks will cross the international date line when appropriate. If the spatial reference cannot be panned, tracks will be limited to the coordinate system extent and may not wrap.
  • PLANARPlanar distances will be used.
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.

  • DWELL_FEATURES All of the input point features that are part of a dwell are returned.
  • DWELL_MEAN_CENTERS Points representing the mean centers of each dwell group are returned. This is the default.
  • DWELL_CONVEX_HULLS Polygons representing the convex hull of each dwell group are returned.
  • ALL_FEATURES All of the input point features are returned.
String
summary_statistics
[summary_statistics,...]
(Optional)

The statistics that will be calculated on specified fields.

  • COUNT—The number of nonnull values. It can be used on numeric fields or strings. The count of [null, 0, 2] is 2.
  • SUM—The sum of numeric values in a field. The sum of [null, null, 3] is 3.
  • MEAN—The mean of numeric values. The mean of [0,2, null] is 1.
  • MIN—The minimum value of a numeric field. The minimum of [0, 2, null] is 0.
  • MAX—The maximum value of a numeric field. The maximum value of [0, 2, null] is 2.
  • STDDEV—The standard deviation of a numeric field. The standard deviation of [1] is null. The standard deviation of [null, 1,1,1] is null.
  • VAR—The variance of a numeric field in a track. The variance of [1] is null. The variance of [null, 1,1,1] is null.
  • RANGE—The range of a numeric field. This is calculated as the minimum value subtracted from the maximum value. The range of [0, null, 1] is 1. The range of [null, 4] is 0.
  • ANY—A sample string from a field of type string.
  • FIRST—The first value of a specified field in a track. Available with ArcGIS Enterprise 10.8.1.
  • LAST—The last value of a specified field in a track. Available with ArcGIS Enterprise 10.8.1.

Value Table
data_store
(Optional)

Specifies the ArcGIS Data Store where the output will be saved. The default is SPATIOTEMPORAL_DATA_STORE. All results stored in the SPATIOTEMPORAL_DATA_STORE will be stored in WGS84. Results stored in a RELATIONAL_DATA_STORE will maintain their coordinate system.

  • SPATIOTEMPORAL_DATA_STOREOutput will be stored in a spatiotemporal big data store. This is the default.
  • RELATIONAL_DATA_STOREOutput will be stored in a relational data store.
String
time_boundary_split
(Optional)

A time span to split your 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 will be split at the beginning of every day.

Time Unit
time_boundary_reference
(Optional)

The reference time used to split your 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 used, January 1, 1970, is used.

Date

Derived Output

NameExplanationData Type
output

The output point or polygon dwell locations.

Record Set

Code sample

FindDwellLocations example 1 (Python window)

The following Python window script demonstrates how to use the FindDwellLocations tool.

# Name: FindDwellLocations.py
# Description: Find the mean centers representing locations where ships have 
# stayed within 15 miles across 4 hours of travel

# Requirements: ArcGIS GeoAnalytics Server

# Import system modules
import arcpy

# Set local variables
inFeatures = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Hurricanes/MapServer/0"
outputName = "AtlanticShips_DwellLocations"
trackIdentifier = "SHIPID"
distance = "15 Miles"
timeDuration = "4 Hours"
outputType = "MEAN_CENTERS"
statistics = [["SPEED", "MEAN"]]

# Execute Find Dwell Locations
arcpy.geoanalytics.FindDwellLocations(inFeatures, outFeatures, trackIdentifier, 
                                      "GEODESIC", distance, timeDuration, 
                                      outputType, statistics, 
                                      "RELATIONAL_DATA_STORE")

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

Related topics