Skip to contents

Computes cumulative detection probabilities and fine-scale positioning probabilities (3+ receivers) across a spatial area using a detection efficiency model. Creates heatmap visualizations of detection coverage.

Enhanced version that handles character station IDs and filters by deployment periods. Computes cumulative detection probabilities and fine-scale positioning probabilities (3+ receivers) across a spatial area for a specific date, considering only receivers that were deployed at that time.

Usage

calculate_detection_system(
  distance_frame,
  receiver_frame,
  model,
  target_date = NULL,
  output_type = "both",
  plots = TRUE,
  station_col = "station_id",
  deploy_col = "deploy_datetime_UTC",
  recover_col = "recover_datetime_UTC"
)

calculate_detection_system(
  distance_frame,
  receiver_frame,
  model,
  target_date = NULL,
  output_type = "both",
  plots = TRUE,
  station_col = "station_id",
  deploy_col = "deploy_datetime_UTC",
  recover_col = "recover_datetime_UTC"
)

Arguments

distance_frame

Data frame containing distance calculations from calculate_station_distances. Must include columns: cell_id, x, y, raster_value, cost_distance, station_no (can be character or numeric).

receiver_frame

An sf object or data frame containing receiver station information. Must include deployment information and coordinates.

model

A fitted model object (e.g., from create_logistic_curve_depth) that can predict detection efficiency. Must accept 'dist_m' and 'depth_m' as predictors.

target_date

Date or POSIXct. The date for which to calculate detection probabilities. Only receivers deployed on this date will be included. If NULL, uses all receivers.

output_type

Character. Type of probabilities to calculate:

  • "cumulative" - Probability of detection by at least one receiver

  • "3_plus" - Probability of detection by 3+ receivers (for positioning)

  • "both" - Calculate both types (default)

plots

Logical. Whether to create and display visualization plots. Default is TRUE.

station_col

Character. Column name in receiver_frame containing station IDs. Default is "station_id". Must match the station identifiers in distance_frame$station_no.

deploy_col

Character. Column name in receiver_frame containing deployment dates. Default is "deploy_datetime_UTC".

recover_col

Character. Column name in receiver_frame containing recovery dates. Default is "recover_datetime_UTC".

Value

If plots = TRUE, returns a list containing:

data

Data frame with spatial coordinates and calculated probabilities

plots

List of individual ggplot objects

combined_plot

Combined plot using patchwork (if both types calculated)

If plots = FALSE, returns only the data frame with calculated probabilities.

If plots = TRUE, returns a list containing:

data

Data frame with spatial coordinates and calculated probabilities

plots

List of individual ggplot objects

combined_plot

Combined plot using patchwork (if both types calculated)

active_stations

Character vector of station IDs active on target_date

n_active_stations

Number of active stations

If plots = FALSE, returns only the data frame with calculated probabilities.

Details

The function performs the following calculations:

  1. Predicts detection efficiency for each cell-receiver pair using the model

  2. Calculates cumulative detection probability: 1 - prod(1 - individual_probs)

  3. Calculates 3+ receiver probability using exact binomial calculations

  4. Creates spatial heatmaps showing detection coverage

The cumulative probability represents the likelihood of detecting a signal anywhere in the system, while the 3+ receiver probability indicates areas where fine-scale positioning is possible.

The model predictions use 'cost_distance' as 'dist_m' and absolute 'raster_value' as 'depth_m' to match expected model inputs.

This enhanced version:

  • Supports both numeric and character station IDs

  • Filters receivers by deployment periods for a specific date

  • Handles flexible column naming for station IDs and deployment dates

  • Provides deployment statistics in the output

  • Maintains compatibility with existing workflows

The function performs the following steps:

  1. Identifies receivers active on the target date

  2. Filters distance_frame to include only active receivers

  3. Predicts detection efficiency for each cell-receiver pair

  4. Calculates cumulative and/or 3+ receiver probabilities

  5. Creates spatial visualizations showing active receiver coverage

Examples

if (FALSE) {
# Generate receiver stations and calculate distances
stations <- generate_random_points(depth_raster, n_points = 6, seed = 123)
distances <- calculate_station_distances(depth_raster, stations, max_distance = 500)

# Create detection efficiency model
de_model <- create_logistic_curve_depth(
  min_depth = 2, max_depth = 30,
  d50_min_depth = 50, d95_min_depth = 20,
  d50_max_depth = 150, d95_max_depth = 60,
  plot = FALSE
)

# Calculate system detection probabilities
detection_system <- calculate_detection_system(
  distance_frame = distances,
  receiver_frame = stations,
  model = de_model$log_model,
  output_type = "both"
)

# Extract results
detection_data <- detection_system$data
positioning_plot <- detection_system$plots$prob_3_plus

# Calculate only positioning probabilities without plots
positioning_only <- calculate_detection_system(
  distance_frame = distances,
  receiver_frame = stations,
  model = de_model$log_model,
  output_type = "3_plus",
  plots = FALSE
)
}

if (FALSE) {
# With character station IDs and deployment filtering
target_date <- as.Date("2023-07-15")

system_DE <- calculate_detection_system(
  distance_frame = station_distances,  # From calculate_station_distances
  receiver_frame = stoney_rx_deploy,   # With deployment information
  model = logistic_DE$log_model,
  target_date = target_date,
  output_type = "both",
  station_col = "station_id",
  deploy_col = "deploy_datetime_UTC",
  recover_col = "recover_datetime_UTC"
)

# Check which stations were active
print(system_DE$active_stations)
print(paste("Active stations:", system_DE$n_active_stations))

# Use all stations (no date filtering)
system_DE_all <- calculate_detection_system(
  distance_frame = station_distances,
  receiver_frame = stoney_rx_deploy,
  model = logistic_DE$log_model,
  target_date = NULL,  # No filtering
  output_type = "cumulative"
)
}