flag_roundtrips: Flag Fast Round Trips

In jmsigner/amt: Animal Movement Tools

Flag Fast Round Trips

Description

Flags locations that imply fast round trips

Usage

flag_roundtrips(x, delta, epsilon, time_unit = "secs", ...)

## S3 method for class 'track_xyt'
flag_roundtrips(x, delta, epsilon, time_unit = "secs", ...)

Arguments

x	⁠[track_xyt]⁠ A track_xyt object.
delta	⁠[numeric]⁠ The threshold SDR for flagging. Locations that imply both legs of a round trip with SDR > delta/epsilon are flagged. See details.
epsilon	⁠[numeric]⁠ A scaling factor to create the threshold for flagging.
time_unit	⁠[character]⁠ Character string giving time unit. Should be "secs", "mins", or "hours". See details.
...	Addtional arguments. None currently implemented.

Details

Locations implying a single fast step can be flagged using flag_fast_steps(). However, it is more likely that a single location is imprecise if it implies an unrealistically fast out-and-back round trip. In that case, the user might be willing to scale the threshold SDR. In this function, delta gives the base SDR and epsilon is the scaling factor, such that locations are considered for flagging if the SDR from the previous location (location i - 1) to the focal location (i) [call it sdr1] and the focal location (i) to the next location (i + 1) [call it sdr2] both have SDR > delta/epsilon.

In that case, the SDR from the previous location (i - 1) to the next location (i + 1) is computed; i.e., the SDR assuming we omit the focal location (i) [call it sdr3]. The remaining locations should be closer together than they are to the omitted location. Thus the focal location is flagged if (sdr1 > epsilon * sdr3) & (sdr2 > epsilon * sdr3).

Note that epsilon both decreases delta in the out-and-back case and increases sdr3 (between the remaining neighbors).

Internally, flagged locations are dropped from future consideration.

The time_unit should be the same time unit with which the SDR threshold was calculated. SDR is typically calculated in m^2/s, so time_unit defaults to "secs". The spatial unit is determined by the CRS, which should typically be in meters. The epsilon parameter is unitless.

Value

Returns x (a track_xyt) with a flagging column added (x$fast_roundtrip_).

Author(s)

Brian J. Smith, based on code by Johannes Signer and Tal Avgar

See Also

flag_duplicates(), flag_fast_steps(), flag_defunct_clusters()

jmsigner/amt documentation built on April 24, 2024, 9:16 a.m.