The soundecology package has functions to calculate indices for soundscape ecology and other ecology research that uses audio recordings. This introduction will provide a brief overview of the indices calculated and the way to use the functions in this package. For more details, please see the literature cited for each index.
soundecology requires R version 2.14, or newer, and depends on the packages tuneR, ineq, vegan, parallel, seewave, pracma, and oce. These packages are installed automatically.
For single-channel files (mono), the results are stored in the left channel, the right channel returns NA.
The package soundecology can calculate several indices:
The examples below use two sound recordings to illustrate the use of the functions:
The ACI is based on the “observation that many biotic sounds, such as bird songs, are characterized by an intrinsic variability of intensities, while some types of human generated noise (such as car passing or airplane transit) present very constant intensity values” (Pieretti, et al. 2011).
To calculate the ACI of the example Wave object tropicalsound, use these commands:
#Load the package
library(soundecology)
#Call the Wave object into memory
data(tropicalsound)
#Run the function
acoustic_complexity(tropicalsound)
To use values other than the defaults:
#Analyze the file only for the frequencies below 8000 Hz
acoustic_complexity(tropicalsound, max_freq = 8000)
#Analyze the file with a cluster size of 10 seconds
acoustic_complexity(tropicalsound, j = 10)
#Analyze the file with a cluster size of 10 seconds and limiting to 6000 Hz
acoustic_complexity(tropicalsound, j = 10, max_freq = 6000)
Example with wav file:
library(soundecology)
#Download a wave file from the web
download.file("http://research.coquipr.com/soundecology/SM87_20080420_000000_10.wav", destfile="SM87_20080420_000000_10.wav")
#Load file as an object called soundfile
soundfile <- readWave("SM87_20080420_000000_10.wav")
#Delete the downloaded wave file
unlink("SM87_20080420_000000_10.wav")
#Run the function on this object and save the results in a new variable called "soundfile.aci"
soundfile.aci <- acoustic_complexity(soundfile)
#Print the ACI value for the left channel of the wav file, stored in soundfile.aci
print(soundfile.aci$AciTotAll_left)
For more details on the function and reference literature, type:
?acoustic_complexity
The Normalized Difference Soundscape Index (NDSI), from REAL (http://www.real.msu.edu) and Kasten, et al. 2012, seeks to “estimate the level of anthropogenic disturbance on the soundscape by computing the ratio of human-generated (anthrophony) to biological (biophony) acoustic components found in field collected sound samples”.
library(soundecology)
data(tropicalsound)
result <- ndsi(tropicalsound)
print(result$ndsi_left)
summary(result)
For more details on the function and reference literature, type:
?ndsi
The Bioacoustic Index, from Boelman et al. 2007, is calculated as the “area under each curve included all frequency bands associated with the dB value that was greater than the minimum dB value for each curve. The area values are thus a function of both the sound level and the number of frequency bands used by the avifauna”.
library(soundecology)
data(tropicalsound)
bioindex <- bioacoustic_index(tropicalsound)
print(bioindex$left_area)
summary(bioindex)
For more details on the function and reference literature, type:
?bioacoustic_index
The Acoustic Diversity Index (ADI), from Villanueva-Rivera et al. 2011, is calculated by dividing the spectrogram into bins (default 10, each one of 1000 Hz) and taking the proportion of the signals in each bin above a threshold (default -50 dBFS). The ADI is the result of the Shannon index applied to these bins.
library(soundecology)
data(tropicalsound)
result <- acoustic_diversity(tropicalsound)
print(result$adi_left)
summary(result)
For more details on the function and reference literature, type:
?acoustic_diversity
The Acoustic Evenness Index (AEI), from Villanueva-Rivera et al. 2011 (band evenness using the Gini index), is calculated by dividing the spectrogram into bins (default 10, each one of 1000 Hz) and taking the proportion of the signals in each bin above a threshold (default -50 dBFS). The AEI is the result of the Gini index applied to these bins.
library(soundecology)
data(tropicalsound)
result <- acoustic_evenness(tropicalsound)
print(result$aei_left)
summary(result)
For more details on the function and reference literature, type:
?acoustic_evenness
The package includes a function that allows you to easily obtain an index for many wav files using a single command. The function multiple_sounds() takes all the wav files in a specified folder and saves the desired index value for each file to a comma-separated file.
In addition, the function can parallelize this task in computers with multiple cores using the parallel package. For example, in a computer with 4 CPU cores, the function can run the analysis in 4 files at a time, which should reduce the total time it takes. By default, the function runs on one file at a time using a single core. To specify to use all available cores, set no_cores to “max”. To allow the function to use all but one core, set no_cores to “-1”.
multiple_sounds() can use the five functions for indices in this package (ndsi(), acoustic_complexity(), acoustic_diversity(), acoustic_evenness(), and bioacoustic_index()) and the H() function from seewave. Set the variable soundindex to the name of the function you want to run in all files.
For example, to calculate the NDSI of files in the folder “wave_files”, using all the cores, and saving the results to a file called ndsi_results.csv, type:
multiple_sounds(directory = "wave_files", resultfile = "ndsi_results.csv", soundindex = "ndsi", no_cores = "max")
To calculate the ADI of files in the folder “wave_files”, using 2 cores, and saving the results to a file called adi_results.csv, type:
multiple_sounds(directory = "wave_files", resultfile = "adi_results.csv", soundindex = "acoustic_diversity", no_cores = 2)
You can also provide variable values of the specific index function. To change the maximum frequency of the biophony of NDSI to 10000 Hz, from the default of 11000, and save the results to a file ndsi_results_10k.csv, type:
multiple_sounds(directory = "wave_files", resultfile = "ndsi_results_10k.csv", soundindex = "ndsi", no_cores = "max", bio_max = 10000)
To calculate the H index from seewave, type:
multiple_sounds(directory = "wave_files", resultfile = "H_results.csv", soundindex = "H")
Note: the csv file will be overwritten if it exists.
Having these indices in the same place is for convenience and to further the study of soundscape ecology and related fields. Calculating all the indices without a priori reasoning must be avoided since it is bad science and raises the probability of Type I errors.
Quoting from the FRAGSTATS website:
the “garbage in- garbage out” axiom applies here. We have done our best in the documentation to stress the importance of defining the landscape at a scale and in a manner that is relevant and meaningful to the phenomenon under consideration. Moreover, we have stressed the importance of understanding the exact meaning of each metric before it is used.
Please visit the package website for more information, and updates: http://ljvillanueva.github.io/soundecology/
For suggestions or to report bugs or problems: http://github.com/ljvillanueva/soundecology/issues
The package page in CRAN is https://cran.r-project.org/package=soundecology
Vignette “An Introduction to soundecology Package” by LJ Villanueva-Rivera
Version 1.01 (16 November 2013)