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:
03_GLMM_modelling.qmd— GLMM-based regression analysis (runs in ~5 minutes)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 (β) coefficientsalpha.samples: Posterior samples for detection (α) coefficientsz.samples: Posterior samples for latent occupancy statessigma.sq.p.samples: Posterior samples for detection random effect variancey: Binary detection matrix (J sites × K replicates) used for fittingX: Design matrix for occupancy covariatesX.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 |