Skip to contents

Plot fish position estimates from acoustic telemetry

Source: R/1.7_function_positioning.R
plot_fish_positions.Rd

Creates visualization plots of fish position estimates showing detection probabilities, non-detection probabilities, and integrated positioning results.

Usage

plot_fish_positions(
  positioning_results,
  depth_raster_df = NULL,
  track_data = NULL,
  fish_select = 1,
  time_select = NULL,
  actual_track_size = 1.2,
  prob_threshold = 0.05,
  detection_threshold = 0.05,
  xlim = NULL,
  ylim = NULL,
  plot_type = "all",
  return_list = FALSE
)

Arguments

positioning_results

A list returned by calculate_fish_positions containing position probabilities and associated data.

depth_raster_df

Optional depth/bathymetry data for background visualization. Can be either a data frame with 'x', 'y' columns or a raster object which will be automatically converted to a data frame.

track_data

Optional complete fish track data for showing full track context. Should be a data frame with columns for fish_id (or path_id), time_seconds, x, y. If not provided, only detection-based track segments will be shown.

fish_select

Numeric. Fish ID to plot. Default is 1.

time_select

Time period to plot. Can be:

  • NULL (default) - Plot all time periods (no filtering)

  • Numeric - Use as time_period value (e.g., 0, 3600, 7200)

  • Character - Interpreted based on format:

    • "YYYY-MM-DD" - Daily time period (e.g., "2024-07-01")

    • "YYYY-MM-DD HH:00" - Hourly time period (e.g., "2024-07-01 15:00")

    • Other formats - Treated as time_period_label

  • POSIXct/POSIXlt - Exact datetime match

actual_track_size

Numeric. Size of the actual track points (green). Default is 1.2.

prob_threshold

Numeric. Minimum probability threshold for display (0-1). Cells below this threshold are not plotted. Default is 0.05.

detection_threshold

Numeric. Minimum detection probability threshold (0-1) for displaying integrated probabilities. Only cells with detection probability above this threshold will show integrated probability values. This prevents artificially high integrated probabilities in areas with no acoustic coverage. Default is 0.05.

xlim

Numeric vector of length 2. X-axis limits for the plot. Default is NULL.

ylim

Numeric vector of length 2. Y-axis limits for the plot. Default is NULL.

plot_type

Character. Type of plot(s) to create. Options are:

  • "detection" - Detection probability only

  • "non_detection" - Non-detection probability only

  • "integrated" - Integrated position probability only

  • "all" - All three plots combined vertically

Default is "all".

return_list

Logical. If TRUE, returns a named list of individual ggplot objects instead of a combined plot. Default is FALSE.

Value

Depending on plot_type and return_list:

  • Single ggplot object (when plot_type is specific type)

  • Combined patchwork plot (when plot_type = "all" and return_list = FALSE)

  • Named list of ggplot objects (when return_list = TRUE)

Details

The function creates up to three types of visualizations:

  1. Detection probability plot showing weighted mean detection efficiency

  2. Non-detection probability plot showing non-detection patterns

  3. Integrated probability plot combining both detection and non-detection data

Plot elements include:

  • Background bathymetry (if provided)

  • Probability surfaces as colored rasters

  • Detecting stations as yellow circles (size = number of detections)

  • Non-detecting stations as red circles

  • Actual fish positions as green circles (if available)

The unified time_select parameter intelligently handles different input types:

  • NULL displays all time periods (no filtering)

  • Numeric values match time_period values

  • Date strings ("YYYY-MM-DD") match daily periods

  • Datetime strings ("YYYY-MM-DD HH:00") match hourly periods

  • Other strings match time_period_label values

  • POSIXct objects match exact datetime values

See also

calculate_fish_positions, analyze_positioning_performance

Examples

if (FALSE) {
# Calculate positions
results <- calculate_fish_positions(station_detections, distances, stations)

# Create all plots for all time periods (default)
plot_fish_positions(results, depth_raster_df = depth_data)

# Create only integrated probability plot for all time
plot_fish_positions(results, plot_type = "integrated")

# Select specific time using numeric value
plot_fish_positions(results, time_select = 3600)

# Select time using date string
plot_fish_positions(results, time_select = "2024-07-01")

# Select time using datetime string
plot_fish_positions(results, time_select = "2024-07-01 15:00")

# Select time using POSIXct object
plot_fish_positions(results, time_select = as.POSIXct("2024-07-01 15:00:00"))

# Customize actual track point size
plot_fish_positions(results, actual_track_size = 2.5)

# Get individual plots as list
plot_fish_positions(results, return_list = TRUE)
plots$detection
plots$integrated
}