Simulate individual trajectory

Simulate the trajectory of a central-place forager over a given time period.

Usage

simulate_trajectory_CPF(
  initial_position,
  resource_layer,
  starting_hour,
  starting_bearing = c(90, 10),
  starting_step = c(4.5, 3),
  travel_bearing = c(0, 20),
  travel_step = c(3, 3),
  foraging_bearing = c(0, 0.5),
  foraging_step = c(1, 3),
  minx = 0,
  maxx = 90,
  miny = 0,
  maxy = 90,
  max_dist = 40,
  step_duration = 1,
  activity_threshold = 0.5,
  max_duration = 720,
  residence_radius = NULL,
  residence_time = NULL
)

Arguments

initial_position: data.frame containing the coordinates of the point the individual starts from (Lon, Lat fields), considered to be the colony location
resource_layer: SpatRaster of the resource layer
starting_hour: Starting hour
starting_bearing: Bearing when departing the colony (mu, kappa)
starting_step: Step length when departing the colony (mu, kappa)
travel_bearing: Bearing from previous step when traveling (mu, kappa)
travel_step: Distance from previous step when traveling (scale, rate)
foraging_bearing: Bearing from previous step when foraging/searching (mu, kappa)
foraging_step: Distance from previous step when foraging (scale, rate)
minx: Minimum longitude of the bounding box to simulate trajectory within
maxx: Maximum longitude of the bounding box to simulate trajectory within
miny: Minimum latitude of the bounding box to simulate trajectory within
maxy: Maximum latitude of the bounding box to simulate trajectory within
max_dist: Distance threshold value above which the individual starts its homing bout
step_duration: Duration of a step length, in minutes (defaults 1), defines the sampling interval
activity_threshold: Threshold environmental value defining when an individual switches from travelling to foraging movement
max_duration: Total duration of a full trip, in minutes (defaults to 720, 12h)
residence_radius: The distance at which testing for residence time (in system unit). This value is used to draw a radius around each position to evaluate the residence time. If one of residence_radius and residence_time is NULL (both, by default), no residence time constraint is applied.
residence_time: The time an animal is allowed to spend in a same area (residence time). Expressed in number of steps (take care to provide a number of step consistent with step_duration). If one of residence_radius and residence_time is NULL (both, by default), no residence time constraint is applied.

Value

a data.frame

Details

The individual launches its trip at a given time period (starting.hour, ymd_hms format) and starts its returning trip either when at a given distance from its colony (provided with max_dist) or after a given time period (max_duration). The user can define the bearing and step distributions for the departing step, but also for the travelling and foraging bouts. By default, travelling are set to be directed movement patterns (large steps with low variability, low angles with low variability) and foraging to be area-restricted movements (short steps with low variability, large angles with large variability). The user can define the step duration, that is the time interval at which the positions are sampled. For each position, ten potential subsequent positions are randomly sampled using potential_position_func, that is with movement parameters based on the activity the individual is engaged in at the previous step (travelling or foraging). The environmental suitability (a raster layer provided with resource_layer) is retrieved for each potential point based on their geographic coordinates, and their distance from the colony is computed using the rdist function from the fields package. The first four positions of the track after colony departure are randomly selected within the ten potential points sampled as described above, using travelling movement. Afterwards, residence time is checked for every points: residence time is considered reached when a user-defined number of previous positions (as defined with residence_time) fall within the residence_radius. If the residence time is reached, the potential subsequent positions falling outside the residence_radius are extracted, and the next position is sampled as the one of them with the highest environmental suitability. If no potential position falls outside the radius (which can be the case when the radius largely exceeds the steps), the next position is the point situated at the largest distance from the previous position in the track. If the residence time is not reached, the subsequent position is randomly sampled among the four out of ten potential points which have the highest values of environmental suitability. If the environmental suitability of the selected subsequent position exceeds a given threshold (activity_threshold), the individual switches to foraging movements; if not, the individual continues travelling. When individuals reach the threshold distance to colony (max_dist), or the trip duration exceeds the given duration (max_duration), they start their homeward journey. Potential next positions are sampled using only travelling movement parameters, and the next positions are selected based on the minimum distance to the colony. If several potential positions meet the selection criteria, the next step is randomly sampled within these positions. An individual is considered back when within 0.5 spatial unit (the unit depends on the provided resource layer) from the colony.

Examples

library(ggplot2)
library(viridis)
#> Loading required package: viridisLite
library(tidyterra)
#> 
#> Attaching package: ‘tidyterra’
#> The following object is masked from ‘package:stats’:
#> 
#>     filter
library(lubridate)
#> 
#> Attaching package: ‘lubridate’
#> The following objects are masked from ‘package:terra’:
#> 
#>     intersect, union
#> The following objects are masked from ‘package:base’:
#> 
#>     date, intersect, setdiff, union
library(terra)
colony_location <- data.frame(Lon = 20, Lat = 20)
cdt <- generate_env_layer(grid = create_grid(), n = 1, seed = 25)
#> [using unconditional Gaussian simulation]
 
# launch a travel for a duration of 12h
single_traj <- simulate_trajectory_CPF(initial_position = colony_location, 
                    resource_layer = cdt$rasters, 
                    starting_hour = ymd_hms("2022-08-02 06:00:00"), 
                    starting_bearing = c(90,10), 
                    starting_step = c(4.5, 3),
                    travel_bearing = c(0, 20), 
                    travel_step = c(3, 3), 
                    foraging_bearing = c(0, 0.5), 
                    foraging_step = c(1, 3),
                    minx = 0, maxx = 90, 
                    miny = 0, maxy = 90,
                    max_dist = 40,
                    step_duration = 5,
                    activity_threshold = 0.70,
                    max_duration = 720,
                    residence_radius = 2,
                    residence_time = 20)

# view the trajectory
ggplot(single_traj) +
  geom_spatraster(data = cdt$rasters, alpha = 0.5) + 
  geom_point(aes(x = Lon, y = Lat, color = activity)) +
  geom_point(data = colony_location, aes(x = Lon, y = Lat), col = "red") +
  scale_fill_viridis(option = "H") 


# look at the density distribution of distance to colony and movement parameters
ggplot(single_traj) + geom_density(aes(x = dist_col))

ggplot(single_traj |> subset(activity %in% c("forage", "travel"))) + 
  geom_density(aes(x = angle)) + facet_wrap("activity")

ggplot(single_traj |> subset(activity %in% c("forage", "travel"))) + 
  geom_density(aes(x = step)) + facet_wrap("activity")

Usage

Arguments

Value

Details

See also

Examples