Find Frequented Locations (AllSource)

Summary

Identifies areas where a movement track has dwelled for multiple time periods and aggregates those locations based on a track identifier.

Usage

  • The tool identifies locations where a movement track has consistently dwelled. This helps in developing a normal pattern of life for a unique movement track identifier and the identification of possible new areas of interest to aid in investigations.

    Pattern of life is a specific set of behaviors and movements associated with an entity over a given period of time. It is used extensively in investigations to better understand when a specific entity was at a given location at a specific time or times.

  • The following terminology is used in the Find Frequented Locations tool:

    • Frequented location—A location representing where multiple dwell locations have intersected in space across multiple time intervals.
    • Dwell location—Features representing when a track has been stationary given specified time and distance parameters.
    • 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, ships with a Maritime Mobile Service Identity (MMSI) report their location in near real time. In this example, the MMSI can represent the distinct tracks.
    • Instant—A single moment in time represented by a start time and no end time. This is sometimes referred to as a time instant.
    • Interval—A duration of time represented by a start time and an end time. This is sometimes referred to as a time interval.

  • The Find Frequented Locations tool differs from the Find Meeting Locations tool in that Find Meeting Locations identifies areas where multiple unique movement tracks are colocated in space and time. The Find Frequented Locations tool identifies locations where a single unique movement track is dwelling in the same location across multiple unique time intervals.

  • Dwell locations are determined using the Minimum Loiter Time and Search Distance parameter values. First, the tool assigns features to a track using a unique identifier. The track order is determined by the time of the features. Next, the distance between the first observation in a track and the next is calculated. Features are considered 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.

    Frequented locations are determined by first identifying all dwell locations present in the dataset. Once they are identified, dwell locations that share the same track identifier are grouped together and merged. If the Minimum Dwells Per Location value is specified, the location must meet the minimum dwells value specified to qualify. Additional statistics will be calculated to find the first and last time the location was visited, total amount of individual dwells at the location, total duration of the location, and a detailed breakdown of the activity per day of the week.

  • By default, the Time Boundary parameter will segment track data at the start of each day at 12:00 a.m. If a dwell location starts on Monday, January 1 at 10:00 p.m. and ends on January 2 at 2:00 a.m., dwell locations will be created for the location on January 1 and January 2.

    If, for the same data, the Time Boundary value is set to 1 week, a single dwell location will be created with a value of 1 in the monday field.

  • Time must be enabled on the Input Features parameter value.

    Learn more about setting time properties on data

  • The Output Feature Class parameter value will contain the following fields:

    • track_id—The unique track identifier derived from the value specified in the Track ID Field parameter
    • area_id—A unique value representing each identified frequented location
    • total_dwells—The number of dwell locations that have been identified for the specified area_id
    • total_time—The sum of the duration in seconds of each individual dwell location
    • location_start—The first observed time instant of the frequented location
    • location_end—The last observed time instant of the frequented location
    • sunday—The amount of individual dwell locations that have occurred in the given area_id on a Sunday
    • monday—The amount of individual dwell locations that have occurred in the given area_id on a Monday
    • tuesday—The amount of individual dwell locations that have occurred in the given area_id on a Tuesday
    • wednesday—The amount of individual dwell locations that have occurred in the given area_id on a Wednesday
    • thursday—The amount of individual dwell locations that have occurred in the given area_id on a Thursday
    • friday—The amount of individual dwell locations that have occurred in the given area_id on a Friday
    • saturday—The amount of individual dwell locations that have occurred in the given area_id on a Saturday

  • If the Normalize Daily Distribution parameter is checked, the values for the sunday, monday, tuesday, wednesday, thursday, friday, and saturday fields will represent the percentage of the total time spent at that location on the particular day of the week. The values will be between 0 and 1, with a value of 1 representing 100 percent. If the Normalize Daily Distribution parameter is unchecked, the value will represent the actual value of the time spent at the particular location on that day of week.

  • This geoprocessing tool is powered by Spark. Analysis is completed on your desktop machine using multiple cores in parallel. For optimal performance, make data available on your desktop machine. If the data isn't local, it will take longer to run this tool.

Parameters

LabelExplanationData Type
Input Features

The input movement track points that will be analyzed for possible frequented locations. The layer must be time enabled.

Feature Layer
Track ID Field

The field containing the unique identifiers that will organize the source data into movement tracks.

Field
Output Feature Class

The output polygon feature class containing the possible frequented locations.

Feature Class
Expression
(Optional)

An SQL expression used to select a subset of records.

SQL Expression
Search Distance
(Optional)

The maximum distance a movement track point can loiter before it is no longer considered part of a frequented location. The default is 100 meters.

Linear Unit
Minimum Loiter Time
(Optional)

The minimum amount of time a movement track point can loiter in an area before it is considered to be dwelling.

This value helps identify possible frequented locations where multiple unique movement tracks are dwelling in the same time and space. The default is 10 minutes.

Time Unit
Time Boundary
(Optional)

The time span that will be used to split the Input Features parameter value. For example, if you use a time boundary of 1 day, tracks will be split at the beginning of every day.

Time Unit
Minimum Dwells Per Location
(Optional)

The minimum number of overlapping individual dwells that will need to occur to be defined as a frequented location. By default, all locations that meet the criteria for a dwell will be returned.

Long
Normalize Daily Distribution
(Optional)

Specifies whether the daily distribution of dwell locations will be normalized. Normalized values represent a percentage of total time that a dwell location occurred on the particular day, while the real values represent the total number of dwells that occurred on the given day.

  • Checked—The daily distribution of dwell locations values will be normalized.
  • Unchecked—The daily distribution of dwell locations values will not be normalized. This is the default.

Boolean
Summary Fields
(Optional)

Specifies the statistics that will be calculated.

Statistics can be calculated for the following variables:

  • Start Time—The time in hours that the individual dwell location was first detected. The time is rounded to the nearest hour.
  • End Time—The time in hours that the individual dwell location was last detected. The time is rounded to the nearest hour.
  • Dwell Duration—The time in seconds that the individual dwell location was active.

The following statistics are supported:

  • Mean—The mean of numeric values.
  • Min—The minimum value of a numeric field.
  • Max—The maximum value of a numeric field.
  • Standard Deviation—The standard deviation of a numeric field.

Value Table

arcpy.intelligence.FindFrequentedLocations(in_features, track_id_field, out_featureclass, {expression}, {search_distance}, {minimum_loiter_time}, {time_boundary}, {minimum_dwells}, {normalize_daily_distribution}, {summary_fields})
NameExplanationData Type
in_features

The input movement track points that will be analyzed for possible frequented locations. The layer must be time enabled.

Feature Layer
track_id_field

The field containing the unique identifiers that will organize the source data into movement tracks.

Field
out_featureclass

The output polygon feature class containing the possible frequented locations.

Feature Class
expression
(Optional)

An SQL expression used to select a subset of records. For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS.

SQL Expression
search_distance
(Optional)

The maximum distance a movement track point can loiter before it is no longer considered part of a frequented location. The default is 100 meters.

Linear Unit
minimum_loiter_time
(Optional)

The minimum amount of time a movement track point can loiter in an area before it is considered to be dwelling.

This value helps identify possible frequented locations where multiple unique movement tracks are dwelling in the same time and space. The default is 10 minutes.

Time Unit
time_boundary
(Optional)

The time span that will be used to split the Input Features parameter value. For example, if you use a time boundary of 1 day, tracks will be split at the beginning of every day.

Time Unit
minimum_dwells
(Optional)

The minimum number of overlapping individual dwells that will need to occur to be defined as a frequented location. By default, all locations that meet the criteria for a dwell will be returned.

Long
normalize_daily_distribution
(Optional)

Specifies whether the daily distribution of dwell locations will be normalized. Normalized values represent a percentage of total time that a dwell location occurred on the particular day, while the real values represent the total number of dwells that occurred on the given day.

  • NORMALIZEDThe daily distribution of dwell locations values will be normalized.
  • REALThe daily distribution of dwell locations values will not be normalized and represent the actual value. This is the default.
Boolean
summary_fields
[summary_fields,...]
(Optional)

Specifies the statistics that will be calculated.

Statistics can be calculated for the following variables:

  • START_TIME—The time in hours that the individual dwell location was first detected. The time is rounded to the nearest hour.
  • END_TIME—The time in hours that the individual dwell location was last detected. The time is rounded to the nearest hour.
  • DWELL_DURATION—The time in seconds that the individual dwell location was active.

The following statistics are supported:

  • MEAN—The mean of numeric values.
  • MIN—The minimum value of a numeric field.
  • MAX—The maximum value of a numeric field.
  • STDDEV—The standard deviation of a numeric field.

Value Table

Code sample

FindFrequentedLocations example (stand-alone script)

The following Python script demonstrates how to use the FindFrequentedLocations function in a stand-alone script.

# Name FindFrequentedLocations.py
# Description: Find frequented locations in a track dataset.

import arcpy

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

fc = "Movement_Tracks"
track_field = "user"
out_fc = "frequented_locations"
where_statement = "user = 'user_1'"
distance = "100 Meters"
loiter_time = "10 Minutes"
boundary = "1 Days"
min_dwells = 5
daily_dist = "NORMALIZED"

arcpy.intelligence.FindFrequentedLocations(fc, 
                                           track_field, 
                                           out_fc, 
                                           where, 
                                           distance, 
                                           loiter_time, 
                                           boundary, 
                                           min_dwells, 
                                           daily_dist)

Licensing information

  • Basic: No
  • Standard: No
  • Advanced: Yes

Related topics