In vulpes-vulpes/batr: Tools for Using Bat Acoustic Monitoring Data in R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

batr

The goal of batr is to streamline analyses and reporting of bat acoustic monitoring data containing GUANO metadata. The package includes code to extract GUANO data directly from attributed WAV files, and to create summaries, plots, and analyses.

The package has been written as part of and to support conservation research by the Toronto Zoo's Native Bat Conservation Program, and is shared here in case it benefits anyone else. It remains a work in progress and feedback and contributions are welcome.

Check development progress and latest changes here.

Winter 2023 Update

A major update was released in Winter 2023 which involves a significant shift in philosophy and rewrite of functionality. This broke all the old functions, which are now depreciated but still present for the time being. However, the trade off is that lots of things work better. New features:

Integrated GUANO code directly (credit, as always to David Riggs) to streamline installation and data import
Streamlined data import and storage approach: you now store the entire project in a single RDATA file that is easier to manage
Added the ability to add extra data to an existing RDATA file rather than recreating from scratch as before, and to update the RDATA file when GUANO in the original WAV files changes
Works with any species codes in your GUANO, i.e. it is no longer hard-coded to only work with the eight bat species of Ontario

If anyone out there wants the old version (0.1.0) you can find it here here and the documentation here. Note that this version is hard-coded for Ontario bat species only.

Installation

Install the current version from GitHub using the following code:

# install.packages("devtools")
devtools::install_github("vulpes-vulpes/batr")

Prerequisite: GUANO

This package is designed to function with bat acoustic monitoring data, in the form of a collection of WAV files, that have been processed to add species identifications and other descriptive information as metadata. Specifically, the metadata should use the GUANO specification (thanks to David Riggs for creating this standard), which us used by most modern bat recording devices and analysis software. At minimum your files need to have the following columns for batr to use them:

Species information in the form of species codes (e.g. "Epfu" for big brown bat, Eptesicus fuscus), either in "Species.Auto.ID" or "Species.Manual.ID", or both, in which case manual ID is taken in preference over auto ID to create a "Species" Column on import
Site names: a data field containing a unique reference name for each site where data was collected, this is specified by name as the "site_col" on import using the import_GUANO function
Timestamp: the date and time when the file was recorded (per GUANO metadata specification)
Loc Position (formatted as decimal lat / lon, e.g.: "00.000000 -00.00000", any number of decimal places can be specified)

Importing Your Data

Importing GUANO from WAV files:

Use the 'import_GUANO' function to import the metadata directly from WAV files. This function takes a folder of WAV files that are recordings of bats with appropriate GUANO metadata already attributed (as described above), finds all the GUANO, and then gives you a new RDATA file that contains all of that GUANO in once place. Along with the directory you want to import, you need to specify the "site_col" (column containing a unique reference for each site where data monitoring occurred), the timezone the data were recorded in, and whether or not you want to create a new RDATA file, add additional data to an existing one, or update an existing RDATA file from files with with changed GUANO.

WHY? Once you have processed a set of acoustic data all the cool and valuable information that you want for fuhrer analyses is in the GUANO metadata (e.g. what species, where, and when). Having that data spread across all the WAV files is unhelpful because: 1) they are relatively huge and you have to lug all that sound data around even when you're not using it; and 2) having that data spread across thousands of small files makes it really slow to read. The batr import_GUANO functions does that slow reading step once and provides a much more portable file to work with thereafter.

Notes: - Reading the GUANO of thousands of small files is s....l....o....w....! Ideally you'll only do it once, and one day it may get faster, but in the meantime pack your patience pills and read from WAV files on an SSD if you can - batr will warn you if your data are missing essential columns, and identify problem files so you can fix them. Unfortunately it has to read them, the slow step, first.

The function to update files previously imported into an RDATA file that have new GUANO does not currently work, fix coming!

Import Recorder Log / Summary Files:

Most automated bat acoustic monitoring hardware produce some form of log file to track device activity, errors etc. These files contain valuable data to determine survey effort: determining whether the unit was active at a given time. This is valuable for many analyses, especially those involving long-term data collection, because it makes it possible to determine whether a result of zero bats observed in a given time period occurred because there were zero bats, or because the recording device was inactive for any reason at that time.

batr currently has the ability to import and parse such files from the following devices:

Anabat Swift: the daily CSV log files output by the Swift should be grouped in one directory per recording location, with the directory name exactly matching the Location / Site Name specified in the GUANO metadata of the WAV files
Wildlife Acoustics SM3BAT, SM4BAT, SMmini: summary TXT files produced by Wildlife Acoustics recorders should be renamed to exactly match the Location / Site Name specified in the GUANO metadata of the WAV files, if there are multiple TXT files for the same monitoring location they can be distinguished with a counter following a hyphen in the file name (e.g. site-1.txt, site-2.txt)

If you wish to see log files from other devices support please get in touch and send example files or a suggestion, and I'll see what I can do.

Once you have your files organised as outlined above, use the 'import_logs' function to add them to an existing RDATA file, or a new one.

Other Functions:

summary_table: outputs a summary table with the total number of observations per species per location
species_daily_site_plot: outputs a plot showing total activity on a nightly basis for a specified species, faceted by location
first_observations_plot: outputs a plot showing the time of the first nightly observation of the specified species relative to local sunset, faceted by location
list_all_locations: outputs a list of all unique locations in the dataset
set_locations_list: allows you to set a list of locations that will be used to subset the data for other functions (e.g. if a location list has been set, any plots created subsequently will only use data from these locations)
show_locations_list: reveals the above list, if set
list_all_species / set_species_list / show_species_list: as above but with species instead of locations
manual_vet_extractor: outputs a copy of random subset of data, filtered by species and / or location as required, to facilitate manual vetting