Calculate the Acoustic Diversity Index on the Files in a Folder

Calculates the Acoustic Diversity Index for all the files in a folder, with extended parameter options. It uses parallel processing with all but one of the available cores. Modifications by Francisco Rivas (frivasfu@purdue.edu // fcorivasf@gmail.com) April 2024.

Usage

adi_folder(
  folder = NULL,
  list = NULL,
  recursive = FALSE,
  start = 0,
  end = 1,
  unit = "minutes",
  save.csv = TRUE,
  csv.name = "adi_results.csv",
  freq.res = 50,
  win.fun = "hanning",
  min.freq = 0,
  max.freq = 10000,
  n.bands = 10,
  cutoff = -60,
  norm.spec = FALSE,
  noise.red = 0,
  rm.offset = TRUE,
  props = FALSE,
  prop.den = 1,
  db.fs = TRUE,
  use.vegan = FALSE,
  n.cores = -1
)

Arguments

folder: a path to the folder with audio files to import.
list: An optional list (subset) of files in the folder to analyze. If provided, files outside the list will be excluded.
recursive: logical. Whether to search Wave files in subfolders. Default is TRUE.
start: numerical. Where to start reading the Wave.
end: numerical. Where to end reading the Wave.
unit: character. Unit of measurement for 'start' and 'end'. Options are 'samples', 'seconds', 'minutes', 'hours'. Default is 'minutes'.
save.csv: logical. Whether to save a csv in the working directory.
csv.name: character vector. When 'save.csv' is TRUE, optionally provide a file name.
freq.res: Numeric. Frequency resolution in Hz. This value determines the "height" of each frequency bin and, therefore, the window length to be used (sampling rate / frequency resolution).
win.fun: window function (filter to handle spectral leakage); "bartlett", "blackman", "flattop", "hamming", "hanning", or "rectangle".
min.freq: minimum frequency to compute the spectrogram
max.freq: maximum frequency to compute the spectrogram
n.bands: number of bands to split the spectrogram
cutoff: dB threshold to calculate energy proportions (if normspec = FALSE, set to 5 or above)
norm.spec: logical. Whether to normalize the spectrogram (not recommended) or not (normalized spectrograms with different SNR are not comparable).
noise.red: numeric. noise reduction (subtract median from the amplitude values); 0=none, 1=rows, 2=columns.
props: logical. Whether to store the energy proportion values for each frequency band and channel (default) or not.
prop.den: numeric. Indicates how the energy proportion is calculated.
db.fs: logical; if TRUE, the amplitude scale is expressed as decibels Full Scale (dBFS). Only used when norm = FALSE.
use.vegan: logical; if TRUE, the diversity() function from the vegan package is called to compute Shannon's entropy. Default = FALSE.
n.cores: The number of cores to use for parallel processing. Use n.cores = -1 to use all but one core. Default is NULL (single-core processing).
rmoff: logical. Whether to remove DC offset before computing ADI (recommended) or not.

Value

a tibble (data frame) with the ADI values for each channel (if stereo), metadata, and the parameters used for the calculation.

Details

Options for propden: 1 = The original calculation from the "soundecology" package is applied. The denominator of the proportion equals to all the cells in the same frequency band. 2 = A "true Shannon" proportion is calculated, where the "whole population across species" equals the cells above the decibel threshold across the spectrogram (up to 'max.freq') It uses parallel processing with all but one of the available cores. Optimized to facilitate working with a list of audio files before importing them into R. Modifications by Francisco Rivas (frivasfu@purdue.edu // fcorivasf@gmail.com) April 2024

Examples

adi_folder("path/to/folder")
#> Working on it...
#> Error in setwd(folder): cannot change working directory