<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{An Introduction to the soundecology package}
-->

# An Introduction to the *soundecology* Package #

## Introduction ##

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*.

## Indices ##

The package *soundecology* can calculate several indices:

 - Acoustic Complexity Index (ACI) from Pieretti *et al.* 2011
 - Normalized Difference Soundscape Index (NDSI) from REAL (http://www.real.msu.edu) and Kasten *et al.* 2012
 - Bioacoustic Index from Boelman *et al.* 2007.
 - Acoustic Diversity Index (ADI) from Villanueva-Rivera *et al.* 2011
 - Acoustic Evenness Index (AEI) from Villanueva-Rivera *et al.* 2011

The examples below use two sound recordings to illustrate the use of the functions:
 - A Wave object included in the package (tropicalsound)
 - A wav file available on the web

### Acoustic Complexity Index (ACI) ###

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
```


### Normalized Difference Soundscape Index (NDSI) ###

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
```


### Bioacoustic Index ###

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
```


### Acoustic Diversity Index (ADI) ###

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
```


### Acoustic Evenness Index (AEI) ###

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
```


## Analysis of many files ##

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.

### "Garbage In, Garbage Out" ###

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](http://www.umass.edu/landeco/research/fragstats/fragstats.html "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.


## Package website ##

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)*