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, start_date, end_date, depth_m (if available). Station information for active stations during analysis period, including deployment dates for temporal filtering.

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 only for station-time combinations where the station was deployed (filters by deployment dates)

7. Formats output compatible with calculate_fish_positions

Note: The function now filters station-time combinations to only include periods when each station was actually deployed. This prevents creation of invalid combinations and reduces memory usage, particularly important for large datasets or long analysis periods.

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

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")
)
}