birdnet_heatmap: Plot heat maps of BirdNET detections by date

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Plot heat maps of BirdNET detections by date

Description

Plot heat maps of BirdNET results for a selected species and above a selected confidence threshold by date for multiple or single year data. See Details.

Usage

birdnet_heatmap(
  data,
  locationID,
  common.name,
  conf.threshold,
  julian.breaks,
  dates.sampled,
  tz.local,
  comparable.color.breaks = FALSE
)

Arguments

data	Data.table or data.frame of BirdNET results that a user would like to plot. Generally, this data object may be preceded by a call to add_time_cols; all data should come from a single site and the object must contain columns named "locationID" (character), "recordingID" (character), and "dateTimeLocal" (POSIXct). Multiple years of data are allowed in one dataset to enable easy comparison of vocal activity by year at a site.
locationID	Character input of the locationID for which data should be plotted.
common.name	Character input of the target species for which data should be plotted.
conf.threshold	Numeric input of the BirdNET confidence threshold above which data should be plotted. All detections below this confidence threshold will be discarded.
julian.breaks	Optional numeric vector of julian date plotting breaks to use on the x axis. If omitted, will be computed automatically. Example inputs: c(140, 160, 180) would graph 3 breaks on the x axis (May 20, June 9, and June 29 for non-leap year data); c(130:160) would graph every single date from May 10 to June 9 on the x axis (for non-leap year data). See also readable_julian_breaks. Please start with 1 for the first day of the year rather than 0.
dates.sampled	Date or character vector of all dates sampled that should be visualized on the heat map. This information is required because your data input may only contain detection data, and not non-detection data (i.e., zeroes). For example, you might have recorded audio on 2021-03-14, but have no BirdNET detections in "data". This will result in an inaccurate visual. Since BirdNET results do not automatically contain non-detection data, it is incumbent on the user to input which dates were sampled.
tz.local	Character Olsen names timezone for local time at the monitoring location (e.g., 'America/Los_angeles').
comparable.color.breaks	Logical flag for whether to create heat map color breaks based on all species in the input data set or based only on the species of interest in this plot. TRUE means it will be easier to make straightforward comparisons between species, FALSE means activity contrasts within a single species will be easier to see.

Details

This function was developed by the National Park Service Natural Sounds and Night Skies Division. It is intended to provide exploratory plotting for summarizing and visualizing BirdNET results.

Function returns a heatmap of BirdNET detections, where N is the number of detections for common.name above conf.threshold on any given day. Note that if you have different sampling efforts on different days, the heat map "as is" may not accurately visualize your target species' vocalization effort. In this case, you may wish to do some preprocessing to your data input to control for differences in sampling effort on different days.

Value

Heat map of BirdNET detections, where N is the number of detections for common.name above conf.threshold on any given day.

See Also

birdnet_barchart birdnet_heatmap_time

Examples

## Not run: 

# Read in example data
data(exampleHeatmapData)
data(exampleDatesSampled)

# Ensure your data has an appropriate recordingID column and time columns
dat <- exampleHeatmapData
dat[ ,recordingID := basename(filepath)]
dat <- add_time_cols(
 dt = dat,
 tz.recorder = 'America/Los_angeles',
 tz.local = 'America/Los_angeles'
)

# Generate a heatmap at Rivendell for Pacific Wren
# Set comparable.color.breaks = FALSE to maximize contrast in a single species map
# Add user-input julian.breaks
birdnet_heatmap(
  data = dat,
  locationID = 'Rivendell',
  common.name = 'Pacific Wren',
  conf.threshold = 0.2,
  dates.sampled = exampleDatesSampled,
  julian.breaks = seq(from = 70, to = 250, by = 30),
  comparable.color.breaks = FALSE
)

# Generate heatmaps for several species with comparable.color.breaks == TRUE
# so that heatmap color scale is conserved for ease of interspecies comparison
sp <- c("Pacific Wren",
        "Pacific-slope Flycatcher",
        "Swainson's Thrush",
        "Wilson's Warbler")

for (i in 1:length(sp)) {

 print(paste0('Working on ', sp[i]))

 g <- birdnet_heatmap(
   data = dat,
   locationID = 'Rivendell',
   common.name = sp[i],
   conf.threshold = 0.2,
   dates.sampled = exampleDatesSampled,
   julian.breaks = seq(from = 70, to = 250, by = 30),
   comparable.color.breaks = TRUE
 )

 print(g)

}


## End(Not run)

nationalparkservice/NSNSDAcoustics documentation built on June 13, 2025, 3:32 a.m.