birdnet_heatmap_time: Plot heat maps of BirdNET detections by date and time of day

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Plot heat maps of BirdNET detections by date and time of day

Description

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

Usage

birdnet_heatmap_time(
  data,
  locationID,
  common.name,
  conf.threshold,
  julian.breaks,
  dates.sampled,
  tz.local,
  comparable.color.breaks = FALSE,
  minute.timestep,
  plot.title,
  hours.sampled,
  y.axis.limits = c(0, 23),
  sun.lines = NULL,
  sun.linetypes = NULL,
  latitude,
  longitude
)

Arguments

data	Data.table or data.frame of BirdNET results that a user would like to plot. Generally, this data object should 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. 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.
minute.timestep	Integer input of how to summarize the data by minute. Any divisor of 60 is allowed in options c(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60).
plot.title	User input plot title if desired
hours.sampled	Either an integer vector declaring which hours were sampled across the monitoring period (e.g., c(6:8, 18:20)), or a list declaring sun-based monitoring based on how many hours before and after sunset were recorded, e.g. list(sunrise = c(1.5, 1.5), sunset = c(1, 1)) means that the schedule recorded 1.5 hours before sunrise until 1.5 hours after, and 1 hour before sunset to 1 hour after. If missing hours.sampled, the function assumes continuous sampling and will display the plot as such; beware that this may misrepresent your data: if you did not sample during all hours, the plot will make it appear as if you did.
y.axis.limits	Length 2 integer vector of hourl limits to show. c(0, 23) is default.
sun.lines	Optional character vector of sun-based lines to plot, from suncalc::getSunlightTimes. Options include: c('sunrise', 'sunriseEnd', 'goldenHourEnd', 'solarNoon', 'goldenHour', 'sunsetStart', 'sunset', 'dusk', 'nauticalDusk', 'night', 'nadir', 'nightEnd', 'nauticalDawn', 'dawn')
sun.linetypes	If using sun.lines, include an accompanying equal-length character vector of linetypes in options: c('solid', 'dashed', 'dotted', 'dotdash', 'longdash', 'twodash')
latitude	Numeric latitude. Required if using sun.lines argument.
longitude	Numeric longitude. Required if using sun.lines argument.

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 by julian date, where N is the number of detections in a timestep for common.name above conf.threshold on any given day. If multiple years of data are input to the function, an average is plotted for that timestep and day. The y-axis shows time of day. Optional inputs allow the user to graph sunrise and sunset-based times on the plot for additional context (see help documentation for getSunlightTimes for details). For multi-year data, all detections are summed and displayed for a given julian date.

Value

Heat map of BirdNET detections across julian date and hour.

See Also

birdnet_heatmap

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-slope Flycatcher
# Set comparable.color.breaks = FALSE to maximize contrast in a single species map
birdnet_heatmap_time(
  data = dat,
  common.name = 'Pacific-slope Flycatcher',
  locationID = 'Rivendell',
  conf.threshold = 0.25,
  dates.sampled = exampleDatesSampled,
  hours.sampled = list(sunrise = c(1.5, 1.5), sunset = c(0, 0)),
  y.axis.limits = c(0, 23),
  julian.breaks = c(30, 60, 90, 120, 150, 180, 210, 240, 270),
  minute.timestep = 5,
  comparable.color.breaks = FALSE,
  tz.local = 'America/Los_angeles',
  latitude = 46.1646,
  longitude = -123.77955,
  sun.lines = c('dusk', 'dawn', 'sunrise', 'sunset'),
  sun.linetypes = c('dotdash', 'longdash', 'dotted', 'solid')
)

# 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_time(
    data = dat,
    common.name = sp[i],
    locationID = 'Rivendell',
    conf.threshold = 0.1,
    dates.sampled = exampleDatesSampled,
    hours.sampled = list(sunrise = c(1.5, 1.5), sunset = c(0, 0)),
    y.axis.limits = c(3, 10),
    julian.breaks = c(30, 60, 90, 120, 150, 180, 210, 240, 270),
    minute.timestep = 1,
    plot.title = sp[i],
    comparable.color.breaks = TRUE,
    tz.local = 'America/Los_angeles',
    latitude = 46.1646,
    longitude = -123.77955,
    sun.lines = c('dawn', 'sunrise'),
    sun.linetypes = c('longdash', 'solid')
  )

  print(g)

}


## End(Not run)

nationalparkservice/NSNSDAcoustics documentation built on March 4, 2025, 10:24 p.m.