Plot simulated fish tracks with detection events

Creates a visualization of simulated fish movement paths overlaid on a raster background, showing detection events and receiver station performance.

Usage

plot_fish_tracks(
  simulation_results,
  raster,
  receiver_frame = NULL,
  show_detections = TRUE,
  path_alpha = 0.7,
  color_by = "path_id",
  point_size = 1.5,
  sample_rate = 1
)

Arguments

simulation_results

List output from simulate_fish_tracks containing tracks and station_detections.

raster

A RasterLayer object used as the background for plotting.

receiver_frame

An sf object containing receiver station locations. Default is NULL.

show_detections

Logical. Whether to display detection events on the plot. Default is TRUE.

path_alpha

Numeric. Transparency level for path lines (0-1). Default is 0.7.

color_by

Character. What to color the tracks by: "path_id" (default), "behavioral_state" (if behavioral states used), or "spawning_phase" (if spawning behavior used). Default is "path_id".

point_size

Numeric. Size of points when plotting states/phases. Default is 1.5.

sample_rate

Numeric. Fraction of points to plot (1 = all points, 0.1 = 10% of points). Useful for long tracks to reduce overplotting. Default is 1.

Value

A ggplot2 object showing fish tracks, detection events, and receiver stations.

Details

The plot includes:

• Raster background (typically depth or habitat)

• Fish movement paths colored by path ID

• Detection events: yellow circles (successful), red X marks (missed)

• Receiver stations: sized by detection count, colored by activity

Receiver station visualization:

• Green circles indicate stations with detections

• Red circles indicate stations with no detections

• Circle size scales with number of detections

The function automatically handles different simulation outputs and adapts the visualization based on available data (tracks only vs. full detection simulation).

See also

simulate_fish_tracks

Examples

if (FALSE) {
# Generate and plot fish tracks
fish_sim <- simulate_fish_tracks(
  raster = depth_raster,
  station_distances = distances,
  n_paths = 2,
  n_steps = 100
)

# Basic plot
plot_fish_tracks(fish_sim, depth_raster, stations)

# Plot without detection events
plot_fish_tracks(fish_sim, depth_raster, stations, show_detections = FALSE)

# Customize path transparency
plot_fish_tracks(fish_sim, depth_raster, stations, path_alpha = 0.5)
}