Comprehensive detection performance analysis with summary and plots

Performs complete analysis of detection performance from fish track simulations, including statistical summaries and visualization plots. This is a convenience function that combines calculation, printing, and plotting in one call.

Usage

analyze_detection_performance(
  simulation_results,
  create_plots = TRUE,
  display_plots = TRUE
)

Arguments

simulation_results

List output from simulate_fish_tracks containing tracks and station_detections data frames.

create_plots

Logical. Whether to generate visualization plots. Default is TRUE.

display_plots

Logical. Whether to display the generated plots. Default is TRUE. Set to FALSE to create plots without displaying them.

Value

A list containing:

statistics

Complete detection statistics from calculate_detection_summaries

plots

List of ggplot2 objects from plot_detection_rates (if create_plots = TRUE)

Returns NULL if no detection data is available.

Details

This function provides a complete workflow for detection analysis:

1. Calculates detection performance statistics

2. Prints formatted summary report to console

3. Creates and displays visualization plots (optional)

4. Returns all results for further analysis

The function is designed for quick analysis and reporting of receiver array performance, making it easy to evaluate different system configurations.

See also

simulate_fish_tracks, calculate_detection_summaries, print_detection_summary, plot_detection_rates

Examples

if (FALSE) {
# Complete analysis with plots
analysis <- analyze_detection_performance(fish_simulation)

# Access overall detection rate
overall_rate <- analysis$statistics$overall$detection_percentage

# Access individual plots
path_plot <- analysis$plots$by_path
station_plot <- analysis$plots$by_station
distribution_plot <- analysis$plots$distribution

# Analysis without plots (faster)
stats_only <- analyze_detection_performance(fish_simulation, create_plots = FALSE)

# Create plots but don't display them (useful in scripts/vignettes)
analysis_quiet <- analyze_detection_performance(fish_simulation, 
                                                create_plots = TRUE, 
                                                display_plots = FALSE)
}