Skip to contents

Simulate fish tracks with correlated random walks and detection events

Source: R/1.6_function_walks_detections.R
simulate_fish_tracks.Rd

Simulates fish movement paths using one of three modes, then generates detection events based on receiver array configuration and detection efficiency.

Usage

simulate_fish_tracks(
  raster,
  station_distances,
  mode = "basic",
  species = NULL,
  n_paths = 1,
  n_steps = 100,
  step_length_mean = 50,
  step_length_sd = 20,
  turning_angle_mean = 0,
  turning_angle_sd = 45,
  time_step = 60,
  start_locations = NULL,
  start_time = as.POSIXct("2025-07-01 08:00:00", tz = "America/Toronto"),
  seed = NULL,
  fish_size_cm = NULL,
  species_params = NULL,
  temperature_data = NULL,
  spawning_behavior = FALSE,
  depth_state_bias = FALSE,
  goal_locations = NULL,
  goal_bias = 0.5,
  goal_tolerance = NULL,
  station_info = NULL,
  temporal_info = NULL,
  de_model = NULL,
  include_barriers = FALSE
)

Arguments

raster

A RasterLayer object defining the study area boundaries.

station_distances

Data frame with receiver detection probabilities.

mode

Character. Movement generation mode. One of:

"basic"

User-specified parametric CRW using step_length_mean/step_length_sd and turning_angle_mean/turning_angle_sd.

"species_empirical"

Resamples step lengths and turn angles from empirical VPS distributions. Requires species.

"species_theory"

3-state behavioral model (cruise/search/rest) with temperature-dependent state transitions, optional spawning behavior, and depth-dependent state bias. Requires species.

Default is "basic".

species

Character. Species name ("Walleye", "Smallmouth Bass", "Muskellunge", "Generic"). Required for species_empirical and species_theory modes. Default is NULL.

n_paths

Integer. Number of fish paths to simulate. Default is 1.

n_steps

Integer. Number of steps per path. Default is 100.

step_length_mean

Numeric. Mean step length in map units (basic mode). Default is 50.

step_length_sd

Numeric. SD of step length (basic mode). Default is 20.

turning_angle_mean

Numeric. Mean turning angle in degrees (basic mode). Default is 0.

turning_angle_sd

Numeric. SD of turning angle in degrees (basic mode). Default is 45.

time_step

Numeric. Time between steps in seconds. Default is 60. Overridden by empirical data in species_empirical mode.

start_locations

Matrix or data frame with x,y coordinates for starting locations. Default is NULL.

start_time

POSIXct object for simulation start time. Default is July 1, 2025 08:00:00 EST.

seed

Numeric. Random seed for reproducible results. Default is NULL.

fish_size_cm

Numeric. Fish length in cm for size-scaled parameters (species_theory mode). Default is NULL.

species_params

Data frame with custom species movement parameters. Default is NULL.

temperature_data

Data frame with daily temperature data (species_theory mode). Default is NULL.

spawning_behavior

Logical. Enable spawning behavior modifications (species_theory mode). Default is FALSE.

depth_state_bias

Logical. Enable depth-dependent state transition bias (species_theory mode). Default is FALSE.

goal_locations

Matrix or data frame with x,y goal coordinates, one row per path. Default is NULL.

goal_bias

Numeric between 0 and 1. Strength of directional bias toward goal. Default is 0.5.

goal_tolerance

Numeric. Distance at which fish is considered "arrived". Default is step_length_mean.

station_info

Data frame with station deployment info for temporal DE. Default is NULL.

temporal_info

Data frame with daily environmental conditions for temporal DE. Default is NULL.

de_model

Model object for temporal DE prediction. Default is NULL.

include_barriers

Logical. Apply barrier masking for detections. Default is FALSE.

Value

A list containing tracks and station_detections data frames.

Details

The mode parameter controls how step lengths and turning angles are generated:

  • basic: Draws from normal (step) and von Mises (turn) distributions

  • species_empirical: Resamples from empirical VPS-derived distributions

  • species_theory: Uses a 3-state behavioral model with temperature effects

Goal-directed movement (goal_locations), barrier masking (include_barriers), and temporal detection efficiency can be combined with any mode.