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, filepath, etc.) are automatically detected by birdnet_detect_columns. Must include columns like common_name, confidence, and datetime.
species: Character scalar or vector specifying the common name(s) of species to visualize. If NULL, no species filtering is applied.
threshold: Either a numeric scalar between 0 and 1 (applied uniformly), or a data frame with columns common_name and threshold for species-specific values. If NULL, no threshold filtering is applied.
min_date: Optional character scalar giving the earliest date to include ("YYYY-MM-DD" format).
max_date: Optional character scalar giving the latest date to include ("YYYY-MM-DD" format).
hour: Optional integer vector (0–23) specifying hours of the day to include in the heatmap.

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