Overview

This post is a walkthrough for conducting a bioacoustic analysis using buzzdetect. The following steps will take you from raw audio files to statistical results; by the end of this walkthrough, you should have a sense of how to shape, analyze, interpret, and visualize buzzdetect results. I’ll share R code, figures, and a few tidbits of hard-earned wisdom to help aspiring bioacousticians plan their experiments and analyses carefully. If you’re using buzzdetect in your research or if you’re just interested in what a bioacoustic workflow looks like, read on!

Step One: Analyze with buzzdetect

Because buzzdetect is in active development, this walkthrough won’t cover buzzdetect analysis in-depth. Hop over to the buzzdetect documentation for instructions on processing audio with buzzdetect.

Choose the full_recordings directory as your input folder; output your results to data/intermediate/full_results. Set the output mode to activations and choose at least the “ins_buzz” neuron for output.

This walkthrough was made using results from model_general_v3. If you use a different model, the results might be a little different.

Step Two: Shape with buzzr

You should now have your buzzdetect results from the five flowers stored in data/intermediate/full_results.

library(buzzr) # for shaping buzzdetect results
library(dplyr)
dir_data <- 'data/intermediate/full_results'  # your results should be here relative to the working directory

results <- buzzr::bin_directory(
1  dir_results=dir_data,
2  thresholds = c(ins_buzz=-1.2),
3  dir_nesting = c('flower','recorder'),
4  posix_formats = '%y%m%d_%H%M',
  tz = 'America/New_York',
5  binwidth = 5,
6  calculate_rate = TRUE
)

head(results)

    flower recorder        bin_datetime detections_ins_buzz frames
    <char>   <char>              <POSc>               <int>  <num>
1: chicory    1_104 2025-07-04 00:00:00                   0    313
2: chicory    1_104 2025-07-04 00:05:00                   1    312
3: chicory    1_104 2025-07-04 00:10:00                   0    313
4: chicory    1_104 2025-07-04 00:15:00                   0    312
5: chicory    1_104 2025-07-04 00:20:00                   3    313
6: chicory    1_104 2025-07-04 00:25:00                   0    312
   detectionrate_ins_buzz
                    <num>
1:            0.000000000
2:            0.003205128
3:            0.000000000
4:            0.000000000
5:            0.009584665
6:            0.000000000

Step Three: Plot

library(ggplot2)

Let’s explore these data a little bit to motivate our statistics and get a sense of what we can do with bioacoustic results. We’ll do our plotting with ggplot2.

Activity curves

First up, my favorite visualization: the activity curve. This is the trend of pollinator activity across the course of the day for each flower. This isn’t a common visualization; usually researchers are interested in point estimates such as the total number of bees. But activity curves flex the immense temporal resolution of bioacoustics

ggplot(
  results,
  aes(
    x = bin_datetime,
    y = detectionrate_ins_buzz,
    color = flower
  )
) +
  geom_point()

Aha! Here’s a common issue: all of these recordings were taken at different times of the season. How are we supposed to plot them on a common X axis? We could coerce the hour and minute to a numeric value so that 0.50 is noon, but then our X axis would be difficult to interpret. buzzr has a convenience function, buzzr::commontime that forces the year, month, and day of any input time value to 2000-01-01, allowing for pretty plotting. Let’s try it.

results_plot <- results %>% 
  # we'll smooth out the curves for nicer plotting
  buzzr::bin(20, calculate_rate = TRUE) %>% 
  mutate(commontime = buzzr::commontime(bin_datetime))

ggplot(
  results_plot,
  aes(
    x = commontime,
    y = detectionrate_ins_buzz,
    color = flower
  )
) +
  geom_point()

Much better. Now, for full beautification.

ggplot(
  results_plot,
  aes(
    x = commontime,
    y = detectionrate_ins_buzz,
    color = flower,
    group = interaction(flower, recorder)
  )
) +
  geom_path() +
  facet_grid(rows=vars(flower), scales='free_y') +
  buzzr::theme_buzzr(14) +
  scale_x_datetime(labels=buzzr::label_hour(), expand=expansion(0,0)) +
  scale_y_continuous(expand=expansion(mult=c(0.02,0.1))) +
  xlab('time of day') +
  ylab('detection rate') +
  theme(legend.position='none')

Lovely!

Point estimates

Sometimes we don’t care about time, we just want to compare total activity rates.

results_summary <- results %>% 
  group_by(flower, recorder) %>% 
  summarize(
    frames = sum(frames),
    detections_ins_buzz = sum(detections_ins_buzz)
  )

ggplot(
  results_summary,
  aes(
    x = flower,
    y = detections_ins_buzz,
    fill = flower,
    color = flower
  )
) +
  geom_boxplot(linewidth=0.8, alpha=0.2) +
  scale_y_continuous(labels = function(l){format(l, big.mark=',')}) +
  buzzr::theme_buzzr(14) +
  theme(legend.position = 'none') +
  ylab('total\ndetections')

Not bad, but what’s with the outliers? Chicory, pumpkin, and watermelon all have dots above the whisker, which are far from the center of the data.

The issue is, these data aren’t remotely normal. In fact, they’re bounded on both ends: you can’t have fewer than 0 detections, but you also can’t have more detections than you have frames. The true nature of these data is a rate, the number of positive frames divided by the total number of frames. We call this the detection rate. A sampling of detection rates near 0.50 is roughly normal, b

As a rate, the data are (0,1) bounded and so they necessarily press up against 0.

ggplot(
  results_summary,
  aes(
    x = flower,
    y = log10(detections_ins_buzz),
    fill = flower,
    color = flower
  )
) +
  geom_boxplot(linewidth=0.8, alpha=0.2) +
  scale_y_continuous(
    labels = function(l){format(10^l, big.mark=',')},
    breaks = log10(c(500, 1000, 2000, 5000, 10000))
  ) +
  buzzr::theme_buzzr(14) +
  theme(legend.position = 'none') +
  ylab('total\ndetections\n(log scale)')

I haven’t found a great way to plot distributions of detection rates. Linear axes squish the data. Log axes are annoying to interpret. Boxplots imply “outliers” that are completely expected. Violin plots promise more than they deliver. The reality is that these data are beta distributed and we might be best off plotting the confidence intervals of the precision and mean parameters, but that makes a very inaccessible figure. My best advice for now: just do a boxplot on the linear scale make sure to note that the outlier dots are completely expected.

Step Four: Model

results_summary$detectionrate_ins_buzz <- results_summary$detections_ins_buzz/results_summary$frames

model_fixed <- betareg::betareg(
  detectionrate_ins_buzz ~ flower,
  data = results_summary
)

contrast_fixed <- emmeans::emmeans(model_fixed, specs = ~flower) |>
  pairs()

plot(contrast_fixed)

contrast_fixed |>
  as.data.frame() |>
  filter(`p.value` < 0.05)

 contrast                estimate          SE  df z.ratio p.value
 chicory - mustard    -0.07853511 0.010148965 Inf  -7.738  <.0001
 chicory - soybean    -0.03613594 0.007717661 Inf  -4.682  <.0001
 mustard - pumpkin     0.08165092 0.009984653 Inf   8.178  <.0001
 mustard - soybean     0.04239918 0.011949612 Inf   3.548  0.0036
 mustard - watermelon  0.07700177 0.010231059 Inf   7.526  <.0001
 pumpkin - soybean    -0.03925174 0.007500868 Inf  -5.233  <.0001
 soybean - watermelon  0.03460259 0.007825124 Inf   4.422  0.0001

P value adjustment: tukey method for comparing a family of 5 estimates 

model_mixed <- glmmTMB::glmmTMB(
  detectionrate_ins_buzz ~ flower + (1 | site),
  data = results_summary,
  family = glmmTMB::beta_family()
)

model_linear <- lm(
  detectionrate_ins_buzz ~ flower,
  data = results_summary
)

car::qqPlot(resid(model_linear))

peaktimes <- results %>% 
  group_by(flower, recorder) %>%
  slice_max(order_by=detections_ins_buzz, with_ties = FALSE) %>% 
  mutate(time_peak = buzzr::time_of_day(bin_datetime, time_format='hour'))

model_peaks <- lm(
  time_peak ~ flower,
  data = peaktimes %>% 
    filter(flower!='pumpkin')
)

car::qqPlot(resid(model_peaks))

Beyond buzzes

I train models that detect acoustic events (namely, pollinator flight buzzes). I’ve labeled countless buzzes from field recordings, but it’s impossible to know for certain the identity of the insect making the buzz. Is it a honey bee? An andrenid bee? A small bumble bee? If we want our models to go beyond detection and towards classification, we need more information. Audio alone is not sufficient to train an acoustic model.

To identify the pollinator producing the buzz, we need video. But video comes with a whole host of headaches, one of which is difficulty of annotation. For annotating audio, we use the wonderful and free Audacity, using label tracks to tag events. For video, there’s not a satisfying equivalent. AudaVid looked promising but wasn’t a smooth experience when we tried it a couple years ago. ELAN is extremely powerful, but dauntingly complex and the spectrogram panel seems to be broken. I’m sure the various paid enterprise solutions are great, but they’re also way more powerful than we need and unless any of these organizations wants to cut me a grant, they’re out of budget.

And as much as I love coding, I can only pull the wool so far over my advisor’s eyes. Building video annotation software as an entomology student is…a hard sell.

Sigh…let’s ask the robots

Holy smokes we’ve come a long way. I tried vibe coding this tool using JetBrains’ Junie maybe a year ago and it was hopeless. I used Google AI Studio with Gemini 3 Pro Preview to create this tool. It perfectly one-shot my initial prompt, although now I’m iterating and refining.

Introducing: SeeNote

SeeNote is an audio-visual event annotation tool. The core philosophy is (i) synced audio+video+spectrogram playback, with (ii) event labeling, while being (iii) as simple and friendly as possible.

Disclaimer: this product is almost entirely vibe coded. I know nothing about react or webapps in general. All processing happens locally on your browser, but check the source code for yourself. I know vibe coding invites a lot of scorn. I’m entirely against it when it comes to data analysis and though I use LLMs extensively for troubleshooting and problem solving when coding, I haven’t pushed any vibe code to buzzdetect. All this said, if this tool outputs the correct labels, I don’t care how it happens under the hood. I’m guessing you don’t either, as long as it isn’t hiding any crypto miners or security vulnerabilities. Proof: I never inspected Audacity’s source code.

I didn’t make SeeNote, I just specified it for the machine to make. I waive all intellectual property rights I may have in this code and provide it to the public domain. You are free to use, copy, modify, and profit from it.