Create a heatmap of BirdNET detections by hour and date — birdnet

Generates a heatmap visualizing the daily activity pattern of a specified species detected in BirdNET output data. The heatmap shows detection counts by hour and date, optionally filtered by species, confidence threshold, date range, and hours of the day.

Usage

birdnet_heatmap(
  data,
  species = NULL,
  threshold = NULL,
  min_date = NULL,
  max_date = NULL,
  hour = NULL
)

Arguments

data: A data frame containing BirdNET output. Relevant columns (e.g., common name, confidence, datetime) are automatically detected by birdnet_detect_columns.
species: Character scalar or vector specifying the common name(s) of species to visualize. If NULL, no species filtering is applied.
threshold: Numeric scalar between 0 and 1, or a data frame with columns scientific_name and threshold, or NULL. If numeric, filters detections below this confidence value. If a data frame, species-specific thresholds are applied. If NULL, no threshold filtering is done.
min_date: Character scalar specifying the earliest date to include (format "YYYY-MM-DD"). If NULL, no lower date limit is applied.
max_date: Character scalar specifying the latest date to include (format "YYYY-MM-DD"). If NULL, no upper date limit is applied.
hour: Integer vector of hours (0–23) specifying which hours of the day to include. If NULL, all hours are included.

Value

A ggplot object showing a heatmap of detections by date (x-axis) and hour (y-axis). The fill color corresponds to detection counts.

Examples

if (FALSE) { # \dontrun{
birdnet_heatmap(
  data = birdnet_output,
  species = "Swainson's Thrush",
  threshold = 0.7,
  min_date = "2024-06-01",
  max_date = "2024-06-30",
  hour = 4:7
)
} # }