SoundShape (version 1.0)

hypo.surf: 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

See Also

plotTangentSpace, geomorph, eigensound, pca.plot

Useful links:

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

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

Examples

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


# }