dist.over.time: Distance moved over time intervals

In SNMA: Stream Network Movement Analyses

Distance moved over time intervals

Description

For a series of time intervals, calculate the distance moved between each point and the previous point matching the given time interval.

Usage

dist.over.time(
  data,
  coords,
  lon.name = "lon",
  lat.name = "lat",
  id.name = "id",
  date.time.name = "date.time",
  units = "days",
  time.diff = 1,
  diff.max = NULL,
  sensitivity.min = 0.1,
  sensitivity.max = 0.1,
  sensitivity.change = 0,
  custom.times = NULL,
  custom.sensitivity = NULL
)

Arguments

data	(list) Output from prep.data.
coords	(data.frame) Data frame containing coordinates for animal locations. It must include a column of animal IDs, columns of latitude and longitude (in decimal degrees projected to the same system as the rest of the data), and a column of dates/times (in POSIX format). All other columns will be ignored.
lon.name	(character) For the coords object, the name of the column of longitudes (in quotes). Default = "lon"
lat.name	(character) For the coords object, the name of the column of latitudes (in quotes). Default = "lat"
id.name	(character) For the coords object, the name of the column of animal identities (in quotes). Default = "id"
date.time.name	(character) For the coords object, the name of the column of dates and times (in a POSIX format). Default = "date.time"
units	(character) One of "secs", "mins", "hours", or "days" specifying the units for all time and sensitivity inputs and outputs
time.diff	(numeric) The amount of time to separate each analysis of distance (i.e., a time interval based on units). Default = 1
diff.max	(numeric) The maximum time interval to analyze. If NULL, it will use the maximum possible interval. Default = NULL
sensitivity.min	(numeric) The minimum (starting) buffer (+/-) around time.diff (i.e., the buffer when time.diff = 1). Default = 0.1
sensitivity.max	(numeric) The maximum buffer (+/-) around time.diff. Default = 0.1
sensitivity.change	(numeric) The amount that the sensitivity should change (both + and -) each time interval. Default = 0
custom.times	(numeric vector) Optional vector of custom time intervals to analyze (overrides time.diff and diff.max)
custom.sensitivity	(numeric vector) Optional vector of custom sensitivities to apply to time intervals (overrides all other sensitivity arguments)

Details

This function calculates movement over given intervals of time. For each coordinate (going from oldest to newest) it looks for matches to previous coordinates where the time difference between them matches the specified interval.

time.diff, diff.max, and units specify the time intervals. time.diff specifies the amount of additional time in each sequential interval, with diff.max specifying the largest time interval. For example, if time.diff = 6, diff.max, = 24 and units = "hours" movement will be calculated over 6 hours, 12 hours, 18 hours, and 24 hours.

Points can be used for multiple time intervals. For example, if time.diff = 1 and units = "days" and an animal was tracked at 12:00 on the 1st, 2nd, 3rd, 5th, and 6th of January, the following pairs of points would be used for each time interval:

• 1 day interval = days 1&2, 2&3, 5&6

• 2 day interval = days 1&3, 3&5

• 3 day interval = days 2&5, 3&6

• 4 day interval = days 1&5, 2&6

• 5 day interval = days 1&6

sensitivity.min, sensitivity.max, and sensitivity.change control a buffer of time (+/-) around each interval. This allows for situations such as radio telemetry where points will rarely match an exact time interval. For example, if the time interval is 24 hours with a 1 hour (+/-) buffer, then for each point, it will look for corresponding points 23-25 hours previously.

In many cases, it may be desirable to increase the buffer slightly as the size of the time intervals increase. The sensitivity.max and sensitivity.change arguments control this. sensitivity.max specifies the maximum value a buffer can have, and sensitivity.change controls the amount of buffer increase for new time interval.

Example: If:

• time.diff = 1

• diff.max = 6

• units = "days"

• sensitivity.min = 0.1

• sensitivity.max = 0.5

• sensitivity.change = 0.1

The function will use intervals of 1, 2, 3, 4, 5, 6 days, and the corresponding buffers will be +/- 0.1, 0.2, 0.3, 0.4, 0.5, 0.5 days.

Note that the units are the same for all entries, and the buffer caps at +/- 0.5 because of diff.max, Thus, for a given coordinate, it will look for corresponding coordinates 0.9-1.1, 1.8-2.2, 2.7-3.3, 3.6-4.4, 4.5-5.5, and 5.5-6.5 days previously.

To remove the buffer entirely, set sensitivity.min = 0, sensitivity.max = 0, and sensitivity.change = 0

To set a fixed buffer, set sensitivity.min and sensitivity.max to the same value and set sensitivity.change = 0

custom.times and custom.sensitivity allow users to supply vectors of times and sensitivities that change at irregular intervals (e.g., 1, 3, 5, 10 days). These arguments override other time and sensitivity arguments.

Note: The default sensitivity values are largely arbitrary, and you should carefully select your own based on your study questions and system.

Note: For a given coordinate and time interval, only one match will be allowed with a previous coordinate. If multiple matches are available within a time interval, only the one that is closest to the specified interval will be retained (in the case of ties, the first is arbitrarily retained). For example, if the time interval is 1 day with a +/- .5 buffer and the following points are available: 2023-01-01 12:00:00, 2023-01-01 13:00:00, and 2023-01-02 12:00:00, then when calculating the distance for 2023-01-02 12:00:00, it will only calculate the distance to the point at 2023-01-01 12:00:00 because it was closer to the specified time interval of 1 day.

Value

A data frame containing the outputs for each point at each time interval.

Columns lat,lon,id, and date.time are for the ending position for the interval analyzed

Column dist = distance moved (m) during a given interval (during the actual.diff prior to the specified point)

Column actual.diff = the exact time between the ending position and the previous point to which it was paired (in the time units specified by units)

Column time.diff = the time interval specified by time.diff (in the time units specified by units)

Column sensitivity = the time buffer (+/-) around the time.diff for the given point (in the time units specified by units)

Note: Although each endpoint will only be matched with one previous point for a given time interval, there may be multiple different end points within that time interval. For example, if time.diff = 1, sensitivity.min = .1, units = "days", and for a given animal, there were points at "2023-06-01 12:00:00", "2023-06-02 12:00:00" and "2023-06-02 12:30:00", the results will include a row with "2023-06-02 12:00:00" as the endpoint and a row with "2023-06-02 12:30:00" as the endpoint (both showing the distance from "2023-06-01 12:00:00"). Depending on the data set and questions being asked, that may create undesirable pseudoreplication and you may need to filter the results based on date or some other criterion.

Note: When reading the time.diff column, remember that points are not necessarily sequential. Thus, days = 1, 2, 3 does not necessarily indicate movement over days 1, 2, and 3 of the study, rather it is movement over that many days, regardless of when in the study the pairs of points occurred. See the vignette for suggestions on visualizing and analyzing these data.

Examples

data(stream.line)
data(nodes)
data(animal.points)

network.20 <- prep.data(
  l = stream.line,
  freq = 20,
  nodes = nodes,
  lon.name = "lon",
  lat.name = "lat",
  node.name = "id"
)

dist.results <- dist.over.time(data=network.20,
  coords=animal.points,
  lon.name="lon.raw",
  lat.name="lat.raw",
  id.name="id",
  date.time.name="date.time",
  units="days",
  time.diff=1,
  diff.max=NULL,
  sensitivity.min=0,
  sensitivity.max=0,
  sensitivity.change=0)

SNMA documentation built on Aug. 27, 2026, 1:08 a.m.