Analyze behavioral state patterns by temperature bins

Creates visualizations showing time spent in each behavioral state and state transition probabilities across different temperature ranges. Only works with simulation results that include behavioral state data.

Usage

analyze_behavioral_temperature(
  simulation_results,
  n_temp_bins = 5,
  create_plots = TRUE,
  time_units = "hours",
  by_fish_id = FALSE
)

Arguments

simulation_results

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

n_temp_bins

Integer. Number of temperature bins to create. Default is 5.

create_plots

Logical. Whether to generate and return plots. Default is TRUE.

time_units

Character. Time units for analysis: "seconds", "minutes", "hours", or "days". Default is "hours".

by_fish_id

Logical. Whether to create separate plots for each fish path. Default is FALSE.

Value

A list containing:

data

Data frame with behavioral statistics by temperature bin

plots

List of ggplot2 objects (if create_plots = TRUE):

• time_in_state: Stacked bar chart showing time in each state by temperature

• transition_probs: Heatmap showing transition probabilities by temperature

Returns NULL if behavioral state data is not available.

Details

The function analyzes behavioral patterns across temperature ranges by:

1. Binning temperature data into equal-width ranges

2. Calculating time spent in each behavioral state per temperature bin

3. Computing state transition probabilities within each temperature bin

4. Creating visualizations of these patterns

See also

simulate_fish_tracks, plot_behavioral_states

Examples

if (FALSE) {
# Analyze behavioral patterns by temperature
temp_analysis <- analyze_behavioral_temperature(fish_sim)

# View the plots
print(temp_analysis$plots$time_in_state)
print(temp_analysis$plots$transition_probs)

# Access the data
behavioral_data <- temp_analysis$data

# Custom temperature bins
analysis_10bins <- analyze_behavioral_temperature(fish_sim, n_temp_bins = 10)

# Individual fish analysis
individual_analysis <- analyze_behavioral_temperature(fish_sim, by_fish_id = TRUE)
}