
Calculate detection system probabilities and create visualization
Source:R/1.5_function_detection_efficiency_prediction.R
, R/calculate_detection_system_enhanced.R
calculate_detection_system.Rd
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:
Predicts detection efficiency for each cell-receiver pair using the model
Calculates cumulative detection probability: 1 - prod(1 - individual_probs)
Calculates 3+ receiver probability using exact binomial calculations
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:
Identifies receivers active on the target date
Filters distance_frame to include only active receivers
Predicts detection efficiency for each cell-receiver pair
Calculates cumulative and/or 3+ receiver probabilities
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"
)
}