calc_returns: Calculate Returns (Multiple Tracks)

View source: R/fidelity_funs_calculate-returns.R

calc_returnsR Documentation

Calculate Returns (Multiple Tracks)

Description

Function to calculate returns on multiple tracks based on spatial and temporal criteria.

Usage

calc_returns(tracks, dist, lag, window = Inf)

Arguments

tracks

Data frame of movement tracks (e.g., output from simulate_tracks(), or a set of real tracks). Must contain columns id (individual identifier), x and y (UTM or lat/long coordinates) at a minimum.

dist

Numeric. Maximum distance to be considered a return. Unit should match the unit of the coordinates: m if UTM, degrees if lat/long.

lag

Numeric. Vector of fidelity lags (unit is locations, e.g., 42 for one week at 6h resolution). See Details for definition of fidelity lag.

window

# Duration of the fidelity window (Inf if from the start of the track, an integer if fixed duration; unit is locations, e.g., 42 for one week at 6h resolution). Default is Inf. See Details for definition of fidelity window.

Details

The fidelity lag defines what are considered "non-consecutive" visits: a visit within distance dist of a previously visited location is non-consecutive if it occurs at least lag days after the latest visit at that location.

The fidelity window encompasses the range of eligible steps for returns to a location. For a location visited at time T, the fidelity window includes steps from time T - lag - window to time T - lag. Steps from T - lag + 1 to T are outside the fidelity window and any revisitations within that period are not counted as returns.

Value

Data frame of movement tracks containing one additional column for each lag indicating whether the location is a return (1) or not (0). Locations outside the fidelity window are assigned NA.


picardis/fidelity documentation built on Dec. 10, 2022, 6:16 a.m.