eigensound: 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)

Author

Pedro Rocha

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

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

Run this code

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)


# \donttest{
# 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))
# }

Run the code above in your browser using DataLab