There is a newer version of the record available.

Published May 26, 2026 | Version v1

Methodological choices influence ecological inference in passive acoustic monitoring of a Neotropical nightjar

Authors/Creators

Description

Methodological choices influence ecological inference in passive acoustic monitoring of a Neotropical nightjar

DOI [blinded for peer review]

Overview

This repository contains the data, code, and reproducible analytical workflow for the manuscript:

Authors (2026). Methodological choices influence ecological inference in passive acoustic monitoring of a Neotropical nightjar. Journal of Avian Biology, Special Issue: From Chirps to Insights. [blinded for peer review]

The study evaluates how sequential analytical decisions in passive acoustic monitoring (PAM) workflows — automated detector choice, confidence thresholds, and statistical modeling framework — jointly influence ecological inference about the environmental drivers of vocal activity in Nyctidromus albicollis (Common Pauraque) in the Pantanal wetlands, Brazil.

Study design

  • Species: Nyctidromus albicollis (Caprimulgidae)
  • Study area: Pantanal wetlands and adjacent Cerrado, Mato Grosso do Sul, Brazil
  • Monitoring sites: 7 sites along a ~180 km environmental gradient
  • Recording period: November 2023 – February 2025
  • Total recordings: 97,906 one-minute audio files
  • Classifiers: BirdNET pre-built global model (v2.4.0) and locally trained custom classifier
  • Confidence thresholds: MaxF1 and MaxPrecision
  • Modeling frameworks: Bernoulli GLMM (lme4) and Bayesian single-season occupancy model (spOccupancy)

Repository structure

All files are deposited as individual uploads on Zenodo (no folder structure). Helper functions (to_mcmc_list, tidy_spocc, etc.) are defined within the Quarto documents and do not require a separate script.

Quarto documents (reproducible workflow)

File Description
01_detector_evaluation.qmd Classifier performance evaluation: precision, recall, F1, ROC/AUC
01_detector_evaluation.html Rendered output
02_threshold_processing.qmd Threshold application and data aggregation (produces analysis-ready datasets)
02_threshold_processing.html Rendered output
03_GLMM_modelling.qmd GLMM analysis
03_GLMM_modelling.html Rendered output
04_occupancy_modelling-model_comparasion.qmd Bayesian occupancy analysis (spOccupancy PGOcc)
04_occupancy_modelling-model_comparasion.html Rendered output

Input data — classifier evaluation

File Description
CM-BirdNet.txt Confusion matrix data for BirdNET pre Built classifier
CM-Custom.txt Confusion matrix data for Custom classifier (test dataset)

Input data — threshold processing

File Description
df_night_clean.txt Full dataset (97,906 recordings) with confidence scores from both classifiers and environmental covariates

Processed data — recording level (occupancy model input)

Each file contains one row per site-night combination, with columns for detection status (pres_thresh), environmental covariates (Temp, RH, moon_illumination), acoustic indices (BIO, ACI), site and night identifiers. These files are produced by 02_threshold_processing.qmd.

File Description
Div_MaxF1.txt Custom classifier, MaxF1 threshold (recording-level)
Div_MaxPrecision.txt Custom classifier, MaxPrecision threshold (recording-level)
PreB_MaxF1.txt BirdNET pre-built, MaxF1 threshold (recording-level)
PB_MaxPrecision.txt BirdNET pre-built, MaxPrecision threshold (recording-level)

Processed data — nightly aggregated (GLMM input)

Each file contains one row per site-night combination, with binary nightly detection and environmental covariates.

File Description
Div_maxf1_agg.csv Custom classifier, MaxF1 threshold (nightly aggregated)
preB_maxf1_agg.csv BirdNET pre-built, MaxF1 threshold (nightly aggregated)

Note on file naming: The threshold processing script (02_threshold_processing.qmd) generates output files with labels PreB_MaxF1, PreB_MaxPrecision, Div_MaxF1, and Div_MaxPrecision. Some downstream scripts reference files with slightly different naming conventions (e.g., PB_MaxPrecision.txt instead of PreB_MaxPrecision.txt; preB_maxf1_agg.csv instead of PreB_MaxF1_agg.txt). The deposited files use the names expected by the analysis scripts.

Classifier model

File Description
Compau_DiverSons.tflite Custom-trained BirdNET classifier for N. albicollis

Pre-fitted models

File Description
nyctidromus_occ_models.rds All 4 fitted PGOcc models in a single named list
model_Custom — MaxF1.rds Individual PGOcc model (Custom, MaxF1)
model_Custom — MaxPrecision.rds Individual PGOcc model (Custom, MaxPrecision)
model_BirdNET — MaxF1.rds Individual PGOcc model (BirdNET, MaxF1)
model_BirdNET — MaxPrecision.rds Individual PGOcc model (BirdNET, MaxPrecision)

The individual model .rds files are copies saved separately to enable memory-efficient posterior predictive checks (see Methods). The file nyctidromus_occ_models.rds contains the same four models in a named list and is loaded at the start of the occupancy analysis document.

Reproducibility

Requirements

  • R >= 4.5.2
  • Quarto >= 1.6
  • Required R packages (with versions used):
Package Version Purpose
lme4 2.0.1 GLMM fitting
spOccupancy 0.9.0 Bayesian occupancy models
DHARMa 0.4.7 Residual diagnostics
coda 0.19-4 MCMC diagnostics
bayesplot 1.11.1 MCMC visualization
glmm.hp 1.0.0 Hierarchical partitioning
ggeffects 2.3.2 Marginal effects
tidyverse 2.0.0 Data wrangling and visualization
purrr 1.0.2 Functional programming
patchwork 1.3.0 Plot composition
ggdist 3.3.2 Posterior distribution plots
kableExtra 1.4.0 Table formatting
soundecology 1.3.3 Acoustic indices (BIO, ACI)
lunar 0.2-1 Moon illumination
easystats 0.7.5 Statistical reporting

Running the analysis

The analytical workflow is split across two Quarto documents:

  1. 03_GLMM_modelling.qmd — GLMM-based regression analysis (runs in ~5 minutes)
  2. 04_occupancy_modelling-model_comparasion.qmd — Bayesian occupancy modeling (runs in ~6–8 hours)

To reproduce:

# Clone the repository

# 1. Render the GLMM analysis
quarto render 03_GLMM_modelling.qmd

# 2. Render the occupancy analysis (WARNING: \~6-8 hours)
quarto render 04_occupancy_modelling-model_comparasion.qmd

Note on computational requirements: The Bayesian occupancy models (4 models × 4 chains × 20,000 iterations) require substantial computation time (~6–8 hours on a MacBook with Apple Silicon) and memory (~8–16 GB RAM). Pre-fitted model objects are provided (.rds files) for users who wish to reproduce downstream analyses (diagnostics, figures, tables) without re-running the MCMC sampler. To use pre-fitted models, set eval: false on the fit-models chunk.

MCMC settings

Parameter Value
Iterations per chain 20,000
Burn-in 4,000
Thinning 10
Chains 4
Posterior samples retained 6,400 (1,600 per chain)
PPC draws 250
Convergence criteria Rhat < 1.05, ESS > 400

Data description

Recording-level data (Div_MaxF1.txt, Div_MaxPrecision.txt, PreB_MaxF1.txt, PB_MaxPrecision.txt)

Each row represents one one-minute recording. These files are the input for the occupancy models.

Column Description
night_site_id Unique identifier for each site-night combination (occupancy “site”)
Site Monitoring site identifier (ARA, BAI, BEP, MIM, REF, UEM, XAR)
night Date of the recording night (YYYY-MM-DD)
DataHora_Formatada Date-time of the recording
pres_thresh Binary detection (1 = species detected above threshold, 0 = not detected)
Temp Temperature (°C) at recording time
RH Relative humidity (%) at recording time
moon_illumination Fraction of lunar disc illuminated (0–1)
BIO Bioacoustic Index (0–4,000 Hz)
ACI Acoustic Complexity Index (full frequency range)

Nightly aggregated data (Div_maxf1_agg.csv, preB_maxf1_agg.csv)

Each row represents one site-night combination. These files are the input for the GLMM analysis.

Column Description
site Monitoring site identifier
date Date of the recording night
n_minutes Number of one-minute recordings in the night
presence Binary nightly detection (1 = species detected at least once)
temp_mean Mean nightly temperature (°C)
rh_mean Mean nightly relative humidity (%)
moon_illumination Fraction of lunar disc illuminated (0–1)
lag_presence Detection status on the previous night (0 or 1)

Fitted occupancy models

The file nyctidromus_occ_models.rds contains a named list with four fitted PGOcc model objects. Each model object includes:

  • beta.samples: Posterior samples for occupancy (β) coefficients
  • alpha.samples: Posterior samples for detection (α) coefficients
  • z.samples: Posterior samples for latent occupancy states
  • sigma.sq.p.samples: Posterior samples for detection random effect variance
  • y: Binary detection matrix (J sites × K replicates) used for fitting
  • X: Design matrix for occupancy covariates
  • X.p: Design matrix for detection covariates

Individual model files (model_Custom — MaxF1.rds, etc.) contain the same objects saved separately to enable memory-efficient posterior predictive checks.

Classifier details

Classifier Model file Threshold (MaxF1) Threshold (MaxPrecision) AUC
BirdNET pre-built BirdNET_GLOBAL_6K_V2.4_Model_FP32.tflite 0.10 0.95 0.869
Custom Compau_DiverSons.tflite 0.40 0.95 0.971

BirdNET-Analyzer version: 2.4.0. Sensitivity setting: 1.0. Frequency range: 1–4,000 Hz.

Audio data

Raw audio files (97,906 WAV files, ~380 GB) are not included in this repository due to their size. Audio data are available upon reasonable request to the corresponding author [blinded for peer review]. Metadata for all recordings (site, date, time, duration, associated environmental data) are included in the processed data files.

License

Data and code are released under CC BY 4.0. Please cite the associated publication when using these materials.

Citation

Authors (2026). Methodological choices influence ecological inference in
passive acoustic monitoring of a Neotropical nightjar. Journal of Avian Biology,
Special Issue: From Chirps to Insights. https://doi.org/10.5281/zenodo.20402320

Contact

[blinded for peer review]

Acknowledgements

[blinded for peer review]

AI disclosure

AI tools (Claude, Anthropic; ChatGPT, OpenAI) were used during manuscript preparation as described in the AI Use Statement of the published article. No AI tool was used to generate or modify primary data. All code was reviewed, tested, and validated by the authors on the study dataset.

Files

df_night_clean.txt

Files (1.2 GB)

Name Size
md5:10272d2f6810edf5215b5d48fd22d3df
89.9 kB Download
md5:2f62042bc660a9b08142ab9632196faa
9.8 kB Download
md5:5d9dbffd892a01f5011dd7db640305a5
73.4 kB Download
md5:70a48c691f46cb26727bc25d6d208ab0
8.6 kB Download
md5:b1963517e5c93f7e189659fb6f107fb1
2.9 MB Download
md5:817714fa6586bb336576d01d1d2ff919
22.2 kB Download
md5:5933eef7caff4e280bca11ba4fba8fba
2.9 MB Download
md5:9cb13cb1fce4c0d69447bcf47b66bb01
34.1 kB Download
md5:04a51f04810c80d3fd5b3d5859b9b0b7
2.5 MB Preview Download
md5:104e4105b2aab197ac96f73b32087de7
2.5 MB Preview Download
md5:e6270c39df685fb8ec96f14a2aae9790
33.4 MB Download
md5:d0abbaa5848cfe7607949a7015a81ebb
80.0 MB Preview Download
md5:d3d200d7ab1cdb2a9de580c756aca76a
73.7 MB Preview Download
md5:0490c2e9eaf0375c272b5be9a59f726f
304.3 kB Preview Download
md5:3ac3936b87ce9ffdc5c370c5b3dce562
293.8 kB Preview Download
md5:93318a6724d7711e9447c04fcb4951b7
73.7 MB Preview Download
md5:254fddcd6147682d3b7f2ab11d24f192
93.4 MB Download
md5:23c233795ce90c3e7b8375de14347173
92.7 MB Download
md5:e036b205b569ac768e8e03d52fc21dad
92.5 MB Download
md5:f310594bd728da7c1973aaf988a70fb4
92.2 MB Download
md5:f969dc43adaadb4a1bd18f1d9cd25e1e
370.8 MB Download
md5:f04c20c357a1606e27bf49f78eed35d7
73.7 MB Preview Download
md5:d5a86926fd6faa99a6da32855065c189
73.7 MB Preview Download
md5:481e70d961c04b268cf05e6d6a396f41
327.8 kB Preview Download
md5:82292a24a741bcc2573bc7579d71955e
317.2 kB Preview Download
md5:a3ce6c9e6be95c41c1033078ec32236a
10.8 kB Preview Download