Plot behavioral states over time with temperature coloring

Creates a time series visualization showing behavioral state transitions for each simulated fish path, with background temperature information. Only works with simulation results that include behavioral state data.

Usage

plot_behavioral_states(
  simulation_results,
  show_temperature = TRUE,
  facet_by_path = NULL,
  time_units = "hours"
)

Arguments

simulation_results

List output from simulate_fish_tracks containing tracks with behavioral_state and water_temp_c columns.

show_temperature

Logical. Whether to show temperature as background color. Default is TRUE.

facet_by_path

Logical. Whether to create separate panels for each fish path. Default is TRUE for multiple paths, FALSE for single path.

time_units

Character. Time units for x-axis: "seconds", "minutes", "hours", or "days". Default is "hours".

Value

A ggplot2 object showing behavioral states over time. Returns NULL if behavioral state data is not available.

Details

The plot shows:

• Behavioral states on y-axis (rest/search/cruise)

• Gray lines connecting state transitions over time

• Points colored by temperature (if show_temperature = TRUE) or behavioral state

• Time progression on x-axis in specified units

When show_temperature = FALSE, state colors are:

• Cruise: Blue (active directed movement)

• Search: Orange (active foraging movement)

• Rest: Red (minimal movement)

When show_temperature = TRUE, point coloring uses the plasma viridis color scale (purple=cold, yellow=warm).

See also

simulate_fish_tracks

Examples

if (FALSE) {
# Simulate fish with behavioral states
fish_sim <- simulate_fish_tracks(
  raster = depth_raster,
  station_distances = distances,
  species = "Walleye",
  fish_size_cm = 45,
  n_paths = 3,
  n_steps = 200
)

# Plot behavioral states with temperature
plot_behavioral_states(fish_sim)

# Plot without temperature background
plot_behavioral_states(fish_sim, show_temperature = FALSE)

# Plot as single panel with time in minutes
plot_behavioral_states(fish_sim, facet_by_path = FALSE, time_units = "minutes")
}