| Label | Explanation | Data 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.
| Boolean |
Summary Fields
(Optional) | Specifies the statistics that will be calculated. Statistics can be calculated for the following variables:
The following statistics are supported:
| Value Table |
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.
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
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})| Name | Explanation | Data 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.
| Boolean |
summary_fields [summary_fields,...] (Optional) | Specifies the statistics that will be calculated. Statistics can be calculated for the following variables:
The following statistics are supported:
| Value Table |
Code sample
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)