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 .
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)
)the output of eigensound analysis with analysis.type = "threeDshape". By default: threeD.out = NULL (i.e. output must be specified before ploting)
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
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)
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)
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
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
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
sampling frequency of ".wav" files (in Hz). Should be the same employed on eigensound(analysis.type="threeDshape"). By default: f = 44100
length of the window for the analysis. Should be the same employed on eigensound(analysis.type="threeDshape"). By default: wl = 512
overlap between two successive windows (in %) for increased spectrogram resolution. Should be the same employed on eigensound(analysis.type="threeDshape"). By default: ovlp = 70
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
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"
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)
rotation of the X-axis. Same as theta from persp3D (plot3D package). By default: rotate.Xaxis = 60
rotation of the Y-axis. Same as phi from persp3D (plot3D package). By default: rotate.Yaxis = 40
similarly as in par, magnification to be used for axis values. By default: cex.axis = 0.9
similarly as in par, magnification to be used for x and y labels. By default: cex.lab = 1.2
similarly as in par, magnification to be used for main titles. By default: cex.main = 1.3
Similarly as in par, intended line width for sampling grid. By default: lwd = 0.1
a character string indicating the label to be written on the x-axis. By default: xlab="Time coordinates"
a character string indicating the label to be written on the y-axis. By default: ylab="Frequency coordinates"
a character string indicating the label to be written on the z-axis. By default: zlab="Amplitude"
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
Pedro Rocha
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.
gm.prcomp, summary.gm.prcomp, plot.gm.prcomp, geomorph, eigensound, pca.plot
Useful links:
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)
Run the code above in your browser using DataLab