SoundShape (version 1.0)

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. semilandmarkns) as an R object, and/or in TPS format <U+2013> the native file format of James Rohlf<U+2019>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),
  trel = tlim,
  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)

trel

only applies when analysis.type = "twoDshape". Set the relative scale to be used on the time (X-axis); relative to the numbers displayed on the X-axis of spectrogram plots. By default: trel = tlim

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

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. (in prep) The shape of sound: A new R package that crosses the bridge between Bioacoustics and Geometric Morphometrics.

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

See Also

align.wave, geomorph, seewave

Useful links:

• https://github.com/p-rocha/SoundShape

• Report bugs at https://github.com/p-rocha/SoundShape/issues

Examples

# NOT RUN {
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)


# }
# NOT RUN {
# 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))
# }
# NOT RUN {
# }