hypo.surf: Hypothetical 3D sound surfaces representing a sample of sound...
In p-rocha/SoundShape: Sound Waves Onto Morphometric Data

hypo.surf

R Documentation

Hypothetical 3D sound surfaces representing a sample of sound waves

Description

Using the coordinates acquired by eigensound(analysis.type = "threeDshape"), this function creates 3D plots containing hypothetical sound surfaces that represent either the mean shape configuration (consensus), or minimum and maximum deformations relative to Principal Components in a Principal Components Analysis (PCA).

Note: The output of hypo.surf must be interpreted along with the ordination of Principal Components (e.g. pca.plot), both featuring the same object used for threeD.out argument. By doing so, hypo.surf enhance the comprehension on how sound shape changed along the ordination plot .

Usage

hypo.surf(
  threeD.out = NULL,
  PC = 1,
  flim = c(0, 4),
  tlim = c(0, 0.8),
  x.length = 70,
  y.length = 47,
  log.scale = TRUE,
  f = 44100,
  wl = 512,
  ovlp = 70,
  plot.exp = FALSE,
  plot.as = "jpeg",
  store.at = NULL,
  rotate.Xaxis = 60,
  rotate.Yaxis = 40,
  cex.axis = 0.5,
  cex.lab = 0.9,
  cex.main = 1.1,
  lwd = 0.1,
  xlab = "Time coordinates",
  ylab = "Frequency coordinates",
  zlab = "Amplitude",
  colkey = list(plot = TRUE, cex.clab = 0.9, cex.axis = 0.8, side = 4, length = 0.5,
    width = 0.7, labels = TRUE, tick = TRUE, lty = 1, lwd = 1, lwd.ticks = 1)
)

Arguments

`threeD.out`	the output of `eigensound` analysis with `analysis.type = "threeDshape"`. By default: `threeD.out = NULL` (i.e. output must be specified before ploting)
`PC`	Principal Component intended for the plot. Alternativaly, it is also possible to create mean shape configuration (consensus) from sample `PC = "mean"`. By default: `PC = 1`
`flim`	modifications of the frequency limits (Y-axis). Vector with two values in kHz. Should be the same employed on `eigensound(analysis.type="threeDshape")` By default: `flim = c(0, 10)`
`tlim`	modifications of the time limits (X-axis). Vector with two values in seconds. Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `tlim = c(0, 1)`
`x.length`	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). Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `x.length = 70`
`y.length`	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). Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `y.length = 47`
`log.scale`	a logical. If `TRUE`, `hypo.surf` 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). Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `log.scale = TRUE`
`f`	sampling frequency of `".wav"` files (in Hz). Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `f = 44100`
`wl`	length of the window for the analysis. Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `wl = 512`
`ovlp`	overlap between two successive windows (in %) for increased spectrogram resolution. Should be the same employed on `eigensound(analysis.type="threeDshape")`. By default: `ovlp = 70`
`plot.exp`	a logical. If `TRUE`, exports the 3D output plot containing mean shape (`PC = "mean"`), or minimum and maximum deformations for the desired Principal Component (e.g. `PC = 1`). Exported plot will be stored on the folder indicated by `store.at`. By default: `plot.exp = FALSE`
`plot.as`	only applies when `plot.exp = TRUE`. `plot.as = "jpeg"` will generate compressed images for quick inspection; `plot.as = "tiff"` or `"tif"` will generate uncompressed high resolution images that can be edited and used for publication. By default: `plot.as = "jpeg"`
`store.at`	only applies when `plot.exp = TRUE`. Filepath to the folder where output plots will be stored. Should be presented between quotation marks. By default: `store.at = NULL` (i.e. user must specify the filepath where plots of hypothetical sound surfaces will be stored)
`rotate.Xaxis`	rotation of the X-axis. Same as `theta` from `persp3D` (`plot3D` package). By default: `rotate.Xaxis = 60`
`rotate.Yaxis`	rotation of the Y-axis. Same as `phi` from `persp3D` (`plot3D` package). By default: `rotate.Yaxis = 40`
`cex.axis`	similarly as in `par`, magnification to be used for axis values. By default: `cex.axis = 0.9`
`cex.lab`	similarly as in `par`, magnification to be used for x and y labels. By default: `cex.lab = 1.2`
`cex.main`	similarly as in `par`, magnification to be used for main titles. By default: `cex.main = 1.3`
`lwd`	Similarly as in `par`, intended line width for sampling grid. By default: `lwd = 0.1`
`xlab`	a character string indicating the label to be written on the x-axis. By default: `xlab="Time coordinates"`
`ylab`	a character string indicating the label to be written on the y-axis. By default: `ylab="Frequency coordinates"`
`zlab`	a character string indicating the label to be written on the z-axis. By default: `zlab="Amplitude"`
`colkey`	Similarly as `plot3D`, a list with parameters for the color key (legend). By default: `colkey = list(plot = TRUE, cex.clab = 0.9, cex.axis = 0.8, side = 4, length = 0.5, width = 0.7, labels = TRUE, tick = TRUE, lty = 1, lwd = 1, lwd.ticks = 1)`. See also `colkey`

Note

Some codes from hypo.surf were adapted from plotTangentSpace function (geomorph package version 3.1.2), which is now deprecated and replaced by current functions gm.prcomp, summary.gm.prcomp and plot.gm.prcomp. More specifically, the code chunk related to the acquisition of hypothetical point configurations from each PC (i.e. warp grids) was the same as in plotTangentSpace. However, the hypothetical configurations from plotTangentSpace were plotted along with ordination of PCs, whereas hypo.surf focuses solely on hypothetical 3D surfaces that represent minimum, maximum and mean deformations relative to each PCs.

Author(s)

Pedro Rocha

References

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.

Examples

data(eig.sample)

# PCA using three-dimensional semilandmark coordinates
pca.eig.sample <- stats::prcomp(geomorph::two.d.array(eig.sample))

# Verify names for each acoustic unit and the order in which they appear
dimnames(eig.sample)[[3]]

# Create factor to use as groups in subsequent ordination plot
sample.gr <- factor(c(rep("centralis", 3), rep("cuvieri", 3), rep("kroyeri", 3)))

# Clear current R plot to prevent errors
grDevices::dev.off()

# Plot result of Principal Components Analysis
pca.plot(PCA.out = pca.eig.sample, groups = sample.gr, conv.hulls = sample.gr,
         main="PCA of 3D coordinates", leg=TRUE, leg.pos = "top")

# Verify hypothetical sound surfaces using hypo.surf
hypo.surf(threeD.out=eig.sample, PC=1, flim=c(0, 4), tlim=c(0, 0.8), x.length=70, y.length=47)

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