Acoustic Evenness Index - folder input — aei

Calculates the Acoustic Evenness 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

aei_folder(
  folder = NULL,
  list = NULL,
  recursive = FALSE,
  start = 0,
  end = 1,
  unit = "minutes",
  save.csv = TRUE,
  csv.name = "aei_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 = TRUE,
  prop.den = 1,
  db.fs = TRUE,
  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 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.
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 norm.spec = 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); 1=rows, 2=columns, 3=none.
rm.offset: logical. Whether to remove DC offset before computing aei (recommended) or not.
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 by manipulating the denominator.
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).
frew.res: the frequency resolution (Hz per bin) to use. From this value the window length for the FFT will be calculated (sampling rate / frequency resolution).

Value

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

Details

Options for prop.den: 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 = The "whole population across species" equals the cells above the decibel threshold across the spectrogram (up to 'max.freq') 3 = The "whole population across species" equals the cells above the decibel threshold across the whole spectrogram (up to the Nyquist frequency. This might return a smaller range of values. 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

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