hypo.surf | R Documentation |

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

`threeD.out` |
the output of |

`PC` |
Principal Component intended for the plot. Alternativaly, it is also possible to create mean shape configuration (consensus) from sample |

`flim` |
modifications of the frequency limits (Y-axis). Vector with two values in kHz. Should be the same employed on |

`tlim` |
modifications of the time limits (X-axis). Vector with two values in seconds. Should be the same employed on |

`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 |

`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 |

`log.scale` |
a logical. If |

`f` |
sampling frequency of |

`wl` |
length of the window for the analysis. Should be the same employed on |

`ovlp` |
overlap between two successive windows (in %) for increased spectrogram resolution. Should be the same employed on |

`plot.exp` |
a logical. If |

`plot.as` |
only applies when |

`store.at` |
only applies when |

`rotate.Xaxis` |
rotation of the X-axis. Same as |

`rotate.Yaxis` |
rotation of the Y-axis. Same as |

`cex.axis` |
similarly as in |

`cex.lab` |
similarly as in |

`cex.main` |
similarly as in |

`lwd` |
Similarly as in |

`xlab` |
a character string indicating the label to be written on the |

`ylab` |
a character string indicating the label to be written on the |

`zlab` |
a character string indicating the label to be written on the |

`colkey` |
Similarly as |

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.

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

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

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.