birdnetprocess

Will Cornwell 2026-01-28

birdnetprocess

birdnetprocess helps you process and visualize BirdNET detection results which can be overwhelming in their volume.

Install

# install.packages("devtools") # if needed
devtools::install_github("traitecoevo/birdnetprocess")
#> Skipping install of 'birdnetprocess' from a github remote, the SHA1 (ad9b8330) has not changed since last install.
#>   Use `force = TRUE` to force installation

Example Usage

1. Extract Start DateTime from a BirdNET Filename

The function parse_birdnet_filename_datetime() assumes filenames follow this pattern: SOMETHING_YYYYMMDD_HHMMSS.BirdNET.selection.table.txt or similar.

Note that this assumes that you’ve set the time right on your recording device and that the filename reflects the true time for the start of that time segment.

The package now supports both common birdnet output types:

• Raven selection tables (.txt, tab-delimited)

• BirdNET Analyzer CSV output (.csv, comma-separated)

2. Read a Single BirdNET File

Use read_birdnet_file() to read one BirdNET selection table.

This will: * Detect if it’s a Raven table (tab-separated) or CSV. * Parse the filename for the start time. * Standardize column names (e.g., Begin Time (s)). * Add start_time and recording_window_time columns.

library(birdnetprocess)
library(dplyr)

# Use example data included in the package
raven_path <- system.file("extdata", "example_raven.txt", package = "birdnetprocess")
csv_path <- system.file("extdata", "example_birdnet.csv", package = "birdnetprocess")

# Create a mock filename with a timestamp for demonstration
# (The example files in extdata don't have timestamps in filenames, so we mock it for the reader)
# In real use, your files should look like: SiteA_20240101_120000.BirdNET.selection.table.txt

# We'll just read them directly for now; start_time will be NA if filename doesn't match
df_raven <- read_birdnet_file(raven_path)
df_csv <- read_birdnet_file(csv_path)

head(df_raven)
#> # A tibble: 2 × 13
#>   Selection View          Channel begin_time_s end_time_s `Low Freq (Hz)`
#>       <dbl> <chr>           <dbl>        <dbl>      <dbl>           <dbl>
#> 1         1 Spectrogram 1       1          1.5        4.5             150
#> 2         2 Spectrogram 1       1          5          8               150
#> # ℹ 7 more variables: `High Freq (Hz)` <dbl>, `Common Name` <chr>,
#> #   `Species Code` <chr>, Confidence <dbl>, file_name <chr>, start_time <dttm>,
#> #   recording_window_time <dttm>
head(df_csv)
#> # A tibble: 2 × 9
#>   begin_time_s end_time_s `Scientific name`  `Common Name`  Confidence
#>          <dbl>      <dbl> <chr>              <chr>               <dbl>
#> 1          1.5        4.5 Turdus migratorius American Robin       0.95
#> 2          5          8   Melospiza melodia  Song Sparrow         0.9 
#> # ℹ 4 more variables: `Species Code` <chr>, file_name <chr>, start_time <dttm>,
#> #   recording_window_time <dttm>

Data Requirements: 1. Filename Format: For automatic time processing, filenames MUST contain a timestamp in the format YYYYMMDD_HHMMSS (e.g., MySite_20240320_060000.BirdNET.txt). 2. File Format: * Raven Selection Table: Tab-delimited .txt. Must have Begin Time (s). * CSV: Comma-delimited .csv. Must have Start (s) or Begin Time (s).

3. Quick Visualization and Statistics

plot_species_counts and summarise_detections provide immediate insights into the detections in your data.

First, let’s read the data from a folder of results (e.g., detections_SL21):

library(birdnetprocess)
library(dplyr)

# Read all files in the folder
data <- read_birdnet_folder("detections_SL21", recursive = FALSE)

Quick Stats

Get a summary of your dataset:

birdnetprocess::summarise_detections(data, confidence = 0.7)
# # A tibble: 7 × 2
#   statistic                   value
#   <chr>                       <chr>
# 1 Number of species           49
# 2 Number of recordings        8042
# 3 Recording window            18 Jan 26 - 19 Jan 26
# 4 Most common species           Black Field Cricket
# 5 Peak hour                   2026-01-19 04:21:02
# 6 Average detections per day  4021
# 7 Average detections per hour 178.7111

Quick Calls

Visualize species counts:

birdnetprocess::plot_species_counts(data, confidence = 0.5)

Top 10 Calls

5. Visualizing Daily Patterns (Day/Night)

You can visualize daily activity patterns with day/night shading (using the suncalc package). Note that you must provide the latitude, longitude, and timezone for the shading to work.

# Generate plot with day/night shading
# Example coordinates for Sydney region
birdnetprocess::plot_top_species(
  data,
  n_top_species = 10,
  confidence = 0.6,
  latitude = -32.44, # Required for suncalc
  longitude = 152.24, # Required for suncalc
  tz = "Australia/Sydney"
)

Day Night Patterns

If you have a folder full of BirdNET files, use read_birdnet_folder() to read them all at once. It will return a single combined tibble (as shown above).

Dependencies

Dependencies (lubridate and ggplot2 are key) should be installed automatically when installing birdnetprocess from GitHub.