Note:
This functionality is currently only supported in Map Viewer Classic (formerly known as Map Viewer). It will be available in a future release of the new Map Viewer.
Workflow diagram
Analysis using GeoAnalytics Tools
Analysis using GeoAnalytics Tools is run using distributed processing across multiple ArcGIS GeoAnalytics Server machines and cores. GeoAnalytics Tools and standard feature analysis tools in ArcGIS Enterprise have different parameters and capabilities. To learn more about these differences, see Feature analysis tool differences.
Terminology
| 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 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 snowplow 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. |
Examples
Ecologists and conservation workers can use the Find Dwell Locations tool to improve the safety of elk during migration seasons. Use the results to implement or improve protected areas in locations where the animals are spending the most time. Stationary movement from elks may represent where they feed or sleep.
The department of transportation wants to improve traffic congestion on highways near exits. Using the Find Dwell Locations tool, an analyst can isolate areas experiencing congestion by identifying vehicle tracks that stay within a certain distance for a certain amount of time.
Usage notes
Input features must be time-enabled point features that represent an instant in 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.
Tracks are represented by the unique combination of one or more track fields. Specify track identifiers by checking the Select one or more fields to identify tracks parameter check box. For example, if the flightID and Destination fields are used as track identifiers, the features ID007, Solden and ID007, Tokyo would be in two separate tracks, since they have different Destination field values.
Both time (Define the temporal search range) and distance (Define the spatial search distance) values are used to determine dwell locations. 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 observation is calculated. Features are considered to be part of a dwell location if two temporally consecutive points stay within the given distance for at least the given duration.
Output dwell locations can be represented in four ways. The table below shows an example of each. Dwell results are uniquely identified using the dwellid field for all output types.
| Output type | 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. Nondwell features 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. |  |
The basic calculation in a dwell location will be a count of the number of features that have been summarized into the dwell. Statistics (count, sum, minimum, maximum, range, mean, standard deviation, and variance) can also be calculated on numerical fields, and statistics (count and any) can be calculated on string fields. The string statistic any returns a sample string from each track. The statistics will be calculated on each dwell location.
In addition to the fields from the input layer and the specified summary statistics, the following fields are included in all output features:
| Field name | Description |
|---|---|
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 or all features. |
start_datetime | The start time created when the output type is mean centers or convex hulls. |
end_datetime | The end time created when the output type is mean centers or convex hulls. |
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 date field will return the time value of the input feature, and all other fields will return a value of null.
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.
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 vessel ID and trip ID 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.
Applying a time interval tracks at a defined interval. For example, if you set the time interval boundary to be 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 is a fast way to accelerate computing time, as it quickly creates smaller tracks for analysis. If splitting by a recurring time interval boundary makes sense for your analysis, it is recommend for big data processing. This parameter is available at 10.8.1.
If Use current map extent is checked, only the features that are visible within the current map extent will be analyzed. If it's not checked, all input features in the input layer will be analyzed, even if they are outside the current map extent.
Limitations
Inputs must be point layers with time-enabled features of type instant.
Any features that do not have time will not be included in the analysis.
When calculating the convex hull and a dwell location is completely stationary (one unique location) or composed of two unique points that are colinear, 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 shows what a 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 within the yellow polygon. The yellow polygon represents the output convex hull result for colinear points. |  |
How Find Dwell Locations works
The following describes how the Find Dwell Locations tool works:
Calculations
Input layers are summarized into dwell locations using a unique identifier. For all output types, count of features and time duration are calculated for each dwell location.
If you selected a summarized output option (Mean centers or Convex hulls), each track can optionally apply numeric statistics (Count,Sum, Minimum, Maximum, Range, Mean, Standard Deviation, Variance, First and Last) or string statistics (Count and Any,First and Last) for the features summarized within a track.
The First and Last statistics return the first or last value in a track. For example, with a time-ordered track with the following values: [Toronto,Guelph,Montreal], the First value is Toronto, and the Last value is Montreal. First and Last statistics are available at 10.8.1.
The count statistic (for strings and numeric fields) counts the number of nonnull values. The count of the following values equals 5: [0, 1, 10, 5, null, 6] = 5. The count of this set of values equals 3: [Primary, Primary, Secondary, null] = 3.
ArcGIS API for Python example
The Find Dwell Locations tool is available through ArcGIS API for Python.
This example finds where ships stayed within a certain distance for a specific amount of time.
# Import the required ArcGIS API for Python modules
import arcgis
from arcgis.gis import GIS
# Connect to your ArcGIS Enterprise portal and confirm that GeoAnalytics is supported
portal = GIS("https://myportal.domain.com/portal", "gis_publisher", "my_password", verify_cert=False)
if not portal.geoanalytics.is_supported():
print("Quitting, GeoAnalytics is not supported")
exit(1)
# Find the point dataset containing track features to find dwell locations from
track_layer_search = portal.content.search("GPSPoints_Halifax_ships", "Feature Layer")
track_layer = track_layer_search[0].layers[0]
# Run the Find Dwell Locations tool
dwell_result = arcgis.geoanalytics.find_locations.find_dwell_locations(input_layer = track_layer,
track_fields = "vessel_ID, shipping_zone",
method = "Geodesic"
distance_tolerance = .5,
distance_unit = "NauticalMiles",
time_tolerance = 6,
time_unit = "Hours",
summary_fields = [{'statisticType' : 'Maximum',
'onStatisticField' : 'Speed'}],
dwell_type = "DwellMeanCenters",
output_name = "ship_dwell_areas")
# Visualize the results if you are running Python in a Jupyter Notebook
processed_map = portal.map()
processed_map.add_layer(dwell_result)
processed_map
Similar tools
Use Find Dwell Locations to summarize track features into dwell locations. Other tools may be useful in solving similar but slightly different problems.
Map Viewer Classic analysis tools
If you are summarizing points or areas into tracks, use the Reconstruct Tracks tool.
To find other relationships within a track dataset based on spatial or attribute values, use the Detect Incidents tool.
ArcGIS Pro analysis tools
The Find Dwell Locations tool is also available in ArcGIS Pro.
To calculate the distances from one feature to the next, use the Near geoprocessing tool.
To run the tool from ArcGIS Pro, your project's active portal must be running ArcGIS Enterprise 10.8 or later. At 10.8, you must sign in to the portal using an account with privileges to perform spatial analysis in the portal.