eigensound: Sound waves onto morphometric data
In p-rocha/SoundShape: Sound Waves Onto Morphometric Data

eigensound

R Documentation

Sound waves onto morphometric data

Description

eigensound is the main feature of SoundShape package. For each ".wav" file on a given folder, the fuction will compute spectrogram data and acquire semilandmarks using a 3D representation of sound (analysis.type = "threeDshape"), allowing its users to acquire, and simultaneously store point coordinates (i.e. semilandmarks) as an R object, and/or in TPS format – the native file format of James Rohlf’s TPS series (Rohlf, 2015).

Moreover, eigensound also allow its user to export 2D and 3D spectrogram images (plot.exp = TRUE) that are helpful during the protocol for error verification and for illustrative purposes (see Rocha & Romano in prep). Alternativaly, eigensound feature the option of acquiring semilandmarks as the cross-correlation between energy quantiles and a curve of relative amplitude from 2D spectrograms (analysis.type = "twoDshape"; see Details section).

Usage

eigensound(
  analysis.type = NULL,
  wav.at = NULL,
  store.at = wav.at,
  dBlevel = 25,
  flim = c(0, 10),
  tlim = c(0, 1),
  x.length = 80,
  y.length = 60,
  log.scale = TRUE,
  back.amp = 35,
  add.points = FALSE,
  add.contour = TRUE,
  lwd = 1,
  EQ = c(0.05, 0.15, 0.3, 0.5, 0.7, 0.85, 0.95),
  mag.time = 1,
  f = 44100,
  wl = 512,
  ovlp = 70,
  plot.exp = TRUE,
  plot.as = "jpeg",
  plot.type = "surface",
  rotate.Xaxis = 60,
  rotate.Yaxis = 40,
  TPS.file = NULL
)

Arguments

`analysis.type`	type of analysis intended. If `analysis.type = "threeDshape"`, semilandmarks are acquired from spectrogram data using a 3D representation of sound (same as in MacLeod et al., 2013). If `analysis.type = "twoDshape"` and `add.points = TRUE`, semilandmarks are acquired using energy quantiles and a 2D curve of relative amplitude. By default: `analysis.type = NULL` (i.e. method must be specified before the analysis).
`wav.at`	filepath to the folder where `".wav"` files are stored. Should be presented between quotation marks. By default: `wav.at = NULL` (i.e. user must specify the filepath to `".wav"` files)
`store.at`	filepath to the folder where spectrogram plots and `tps` file will be stored. Should be presented between quotation marks. By default: `store.at = wav.at` (i.e. store outputs in the same folder as `".wav"` files)
`dBlevel`	absolute amplitude value to be used as relative amplitude contour, which will serve as reference for semilandmark acquisition in both `analysis.type = "threeDshape"` and `"twoDshape"`. By default: `dBlevel = 25`
`flim`	modifications of the frequency limits (Y-axis). Vector with two values in kHz. By default: `flim = c(0, 10)`
`tlim`	modifications of the time limits (X-axis). Vector with two values in seconds. By default: `tlim = c(0, 1)`
`x.length`	only applies when `analysis.type = "threeDshape"`. Length of sequence (i.e. number of cells per side on sound window) to be used as sampling grid coordinates on the time (X-axis). By default: `x.length = 80`
`y.length`	only applies when `analysis.type = "threeDshape"`. Length of sequence (i.e. number of cells per side on sound window) to be used as sampling grid coordinates on the frequency (Y-axis). By default: `y.length = 60`
`log.scale`	only applies when `analysis.type = "threeDshape"`. A logical. If `TRUE`, `eigensound` will use a logarithmic scale on the time (X-axis), which is recommeded when the analyzed sounds present great variation on this axis (e.g. emphasize short duration sounds). If `FALSE`, a linear scale is used instead (same as MacLeod et al., 2013). By default: `log.scale = TRUE`
`back.amp`	only applies when `analysis.type = "twoDshape"` and `plot.exp = TRUE`. Absolute amplitude value to be used as background in the 2D spectrogram plot. By default: `back.amp = 35`
`add.points`	only applies when `analysis.type = "twoDshape"`. A logical. If `TRUE`, `eigensound` will compute semilandmarks acquired by cross-correlation between energy quantiles (i.e. `EQ`) and a curve of relative amplitude (i.e. `dBlevel`). If `plot.exp = TRUE`, semilandmarks will be included in spectrogram plots. By default: `add.points = FALSE` (see `Details`)
`add.contour`	only applies when `analysis.type = "twoDshape"` and `plot.exp = TRUE`. A logical. If `TRUE`, exported spectrogram plots will include the curves of relative amplitude at the level specified by `dBlevel`. By default: `add.contour = TRUE`
`lwd`	only applies when `plot.exp = TRUE` and `add.contour = TRUE`. The line width for the curves of relative amplitude at the level specified by `dBlevel`. Same as in `par`. By default: `lwd = 1`
`EQ`	only applies when `analysis.type = "twoDshape"` and `add.points = TRUE`. A vector of energy quantiles intended (with `0 < EQ < 1`). By default: `EQ = c(0.05, 0.15, 0.3, 0.5, 0.7, 0.85, 0.95)` Note: When dealing with narrow banded calls, consider reducing the number of quantiles to prevent errors in the analysis.
`mag.time`	only applies when `analysis.type = "twoDshape"`. Optional argument for magnifying the time coordinates (X-axis). This is sometimes desired for small sound windows (e.g. less than 1 s), in which the time coordinates will be on a different scale than that of frequency coordinates. In those cases, it is recommended to include `mag.time = 10` or `mag.time = 100`, depending on the lenght of sound window. By default: `mag.time = 1` (i.e. no magnification is performed)
`f`	sampling frequency of `Wave`'s for the analysis (in Hz). By default: `f = 44100`
`wl`	length of the window for the analysis. By default: `wl = 512`
`ovlp`	overlap between two successive windows (in %) for increased spectrogram resolution. By default: `ovlp = 70`
`plot.exp`	a logical. If `TRUE`, for each `".wav"` file on the folder indicated by `wav.at`, `eigensound` will store a spectrogram image on the folder indicated by `store.at`. Depending on the `analysis.type`, plots may consist of 2D or 3D spectrogram images. By default: `plot.exp = TRUE`
`plot.as`	only applies when `plot.exp = TRUE`. `plot.as = "jpeg"` will generate compressed images for quick inspection of semilandmarks; `plot.as = "tiff"` or `"tif"` will generate uncompressed high resolution images that can be edited and used for publication. By default: `plot.as = "jpeg"`
`plot.type`	only applies when `analysis.type = "threeDshape"` and `plot.exp = TRUE`. `plot.type = "surface"` will produce simplified 3D sound surfaces from the calculated semilandmarks (same output employed by MacLeod et al., 2013); `plot.type = "points"` will produce 3D graphs with semilandmarks as points. By default: `plot.type = "surface"`
`rotate.Xaxis`	only applies when `analysis.type = "threeDshape"` and `plot.exp = TRUE`. Rotation of the X-axis. Same as `theta` from `persp3D` (`plot3D` package). By default: `rotate.Xaxis = 60`
`rotate.Yaxis`	only applies when `analysis.type = "threeDshape"` and `plot.exp = TRUE`. Rotation of the Y-axis. Same as `phi` from `persp3D` (`plot3D` package). By default: `rotate.Yaxis = 40`
`TPS.file`	Desired name for the `tps` file containing semilandmark coordinates. Should be presented between quotation marks. Note: Whenever `analysis.type = "twoDshape"`, it will only work if `add.points = TRUE`. By default: `TPS.file = NULL` (i.e. prevents `eigensound` from creating a `tps` file)

Details

When analysis.type = "twoDshape" and add.points = TRUE, eigensound will compute semilandmarks acquired by cross-correlation between energy quantiles (i.e. EQ) and a curve of relative amplitude (i.e. dBlevel). However, this is often subtle and prone to incur in errors (e.g. bad alignment of acoustic units; inappropriate X and Y coordinates for the sound window; narrow banded calls). Therefore, a more robust protocol of error verification is achieved using add.points = FALSE and add.contour = TRUE (default), which allow for quick verification of acoustic units alignment and the shape of each curve of relative amplitude (specified by dBlevel).

Note

In order to store the results from eigensound function and proceed with the Geometric Morphometric steps of the analysis (e.g. geomorph package; Adams et al., 2017), one can simultaneosly assign the function's output to an R object and/or store them as a tps file to be used by numerous softwares of geometric analysis of shape, such as the TPS series (Rohlf, 2015).

Additionally, one may also export 2D or 3D plots as jpeg (compressed image) or tiff (uncompressed image) file formats, which can be edited for publication purposes.

Author(s)

Pedro Rocha

References

Adams, D. C., M. L. Collyer, A. Kaliontzopoulou & Sherratt, E. (2017) Geomorph: Software for geometric morphometric analyses. R package version 3.0.5. https://cran.r-project.org/package=geomorph.

MacLeod, N., Krieger, J. & Jones, K. E. (2013). Geometric morphometric approaches to acoustic signal analysis in mammalian biology. Hystrix, the Italian Journal of Mammalogy, 24(1), 110-125.

Rocha, P. & Romano, P. (2021) The shape of sound: A new R package that crosses the bridge between Bioacoustics and Geometric Morphometrics. Methods in Ecology and Evolution, 12(6), 1115-1121.

Rohlf, F.J. (2015) The tps series of software. Hystrix 26, 9-12.

Examples

library(seewave)
library(tuneR)

# Create temporary folder to store ".wav" files
wav.at <- file.path(base::tempdir(), "eigensound")
if(!dir.exists(wav.at)) dir.create(wav.at)

# Create temporary folder to store results
store.at <- file.path(base::tempdir(), "eigensound-output")
if(!dir.exists(store.at)) dir.create(store.at)

# Cut acoustic units from original Wave
cut.cuvieri <- cutw(cuvieri, f=44100, from=0, to=0.9, output = "Wave")
cut.centralis <- cutw(centralis, f=44100, from=0, to=0.9, output = "Wave")
cut.kroyeri <- cutw(kroyeri, f=44100, from=0.2, to=1.1, output = "Wave")

# Export ".wav" files containing acoustic units and store on previosly created folder
writeWave(cut.cuvieri, filename = file.path(wav.at, "cut.cuvieri.wav"), extensible = FALSE)
writeWave(cut.centralis, filename = file.path(wav.at, "cut.centralis.wav"), extensible = FALSE)
writeWave(cut.kroyeri, filename = file.path(wav.at, "cut.kroyeri.wav"), extensible = FALSE)



# Create 2D spectrograms using analysis.type = "twoDshape"
eigensound(analysis.type = "twoDshape", flim=c(0, 4), tlim=c(0, 0.8),
           plot.exp=TRUE, wav.at = wav.at, store.at = store.at)

# Create 3D spectrograms using analysis.type = "threeDshape" and store point coordinates
eig.data <- eigensound(analysis.type = "threeDshape", plot.exp=TRUE,
              wav.at = wav.at, store.at = store.at, flim=c(0, 4), tlim=c(0, 0.8))

p-rocha/SoundShape documentation built on Aug. 29, 2023, 10:57 p.m.