Prepare real fish detection data for WADE positioning

Converts sparse real fish detection data into the time-aggregated format required by calculate_fish_positions function. Creates detection summaries by time period and validates station deployment consistency.

Usage

prepare_detection_data_for_wade(
  fish_detections,
  station_deployments,
  selected_fish_id,
  time_aggregation = "day",
  start_time = NULL,
  end_time = NULL
)

Arguments

fish_detections

Data frame containing fish detection records with columns: fish_id, station_id, detection_timestamp_utc, and optionally species.

station_deployments

Data frame or sf object containing station deployment information with columns: station_id, x, y, deploy_datetime_UTC, recover_datetime_UTC.

selected_fish_id

Character. ID of the fish to process. Must exist in fish_detections$fish_id.

time_aggregation

Character. Time period for aggregating detections. Options: "hour", "day", "week", "month". Default is "day".

start_time

POSIXct. Start time for the analysis period. If NULL, uses the first detection time for the selected fish.

end_time

POSIXct. End time for the analysis period. If NULL, uses the last detection time for the selected fish.

Value

A list containing:

station_detections

Data frame with columns: path_id, datetime, station_id, detected, detection_prob, distance_to_station, station_x, station_y, n_detections. Compatible with calculate_fish_positions function.

station_info

Data frame with columns: station_id, x, y, depth_m (if available). Station information for active stations during analysis period.

time_periods

Data frame with time period information: time_period, time_period_label, n_detections.

deployment_warnings

Character vector of any deployment warnings.

summary_stats

List with analysis summary statistics.

Details

This function performs the following steps:

1. Filters detections for the selected fish

2. Determines analysis time period (start_time to end_time)

3. Identifies stations active during the analysis period

4. Warns if any stations are deployed/recovered during analysis

5. Aggregates detections by time period (hour/day/week/month)

6. Creates detection summary with presence/absence for each station-time combination

7. Formats output compatible with calculate_fish_positions

The station_detections output structure:

• path_id: Always 1 (single fish track)

• datetime: Time period timestamp

• station_id: Station identifier (character, will be converted by WADE function)

• detected: 1 if fish detected at this station during time period, 0 otherwise

• detection_prob: 1.0 for detections, 0 for non-detections (field data certainty)

• distance_to_station: 0 for detections (fish at station), NA for non-detections

• station_x, station_y: Station coordinates

• n_detections: Number of detections in this time period at this station

See also

calculate_fish_positions, prepare_detection_data_for_particle_filter

Examples

if (FALSE) {
# Prepare data for a specific fish with daily aggregation
wade_data <- prepare_detection_data_for_wade(
  fish_detections = stoney_fish_detections,
  station_deployments = stoney_rx_deploy,
  selected_fish_id = "Walleye-1512985",
  time_aggregation = "day"
)

# Check for deployment warnings
if (length(wade_data$deployment_warnings) > 0) {
  cat("Deployment warnings:\n")
  cat(paste(wade_data$deployment_warnings, collapse = "\n"))
}

# Use with WADE positioning
results <- calculate_fish_positions(
  station_detections = wade_data$station_detections,
  station_distances_df = station_distances,
  station_info = wade_data$station_info,
  # ... other parameters
)

# Hourly aggregation for fine-scale analysis
wade_data_hourly <- prepare_detection_data_for_wade(
  fish_detections = stoney_fish_detections,
  station_deployments = stoney_rx_deploy,
  selected_fish_id = "Walleye-1512985",
  time_aggregation = "hour",
  start_time = as.POSIXct("2023-10-15 00:00:00", tz = "UTC"),
  end_time = as.POSIXct("2023-10-17 00:00:00", tz = "UTC")
)
}