threeDspectro: 3D spectrogram plots from '"Wave"' objects
In p-rocha/SoundShape: Sound Waves Onto Morphometric Data

threeDspectro

R Documentation

3D spectrogram plots from `"Wave"` objects

Description

Create 3D spectrograms from a single object of class "Wave".

This function works similarly as spectro (seewave package), with spectrogram data internally computed by spectro. However, the 3D plot is generated by persp3D (plot3D package).

Usage

threeDspectro(
  wave,
  tlim = NULL,
  flim = NULL,
  samp.grid = FALSE,
  plot.type = "surface",
  along = "x",
  skip.lines = 5,
  space.lines = 0.6,
  x.length = 100,
  y.length = 70,
  lwd = 0.1,
  plot.exp = FALSE,
  log.scale = FALSE,
  cex = 0.5,
  cex.axis = 0.5,
  cex.lab = 0.9,
  cex.main = 1,
  store.at = NULL,
  plot.as = "jpeg",
  color = seewave::spectro.colors(80),
  f = 44100,
  wl = 512,
  ovlp = 70,
  dBlevel = 30,
  resfac = 1,
  rotate.Xaxis = 60,
  rotate.Yaxis = 40,
  main = "Spectrogram 3D",
  scalelab = expression("Amplitude (dB)"),
  colkey = list(plot = TRUE, cex.clab = 0.8, cex.axis = 1, side = 4, length = 1, width =
    1, labels = TRUE, tick = TRUE, lty = 1, lwd = 1, lwd.ticks = 1)
)

Arguments

`wave`	an `R` object of the class `"Wave"`
`tlim`	modifications of the time limits (X-axis). Vector with two values in seconds. By default: `tlim = NULL`
`flim`	modifications of the frequency limits (Y-axis). Vector with two values in kHz. By default: `flim = NULL`
`samp.grid`	a logical. If `TRUE`, a sampling grid with dimensions `x.length` and `y.length` is applied over the three-dimensional surface. An amplitude value is collected at each node in the grid and a new matrix of amplitude coordinates is used in the plot. Recommended for faster plots and as protocol for error verification in point acquisition. See also `plot.type`. By default: `samp.grid = FALSE`
`plot.type`	allows the choice between `"lines"`, `"surface"` or `"points"`. Beware that `"points"` only applies when `samp.grid = TRUE`. `plot.type = "surface"` will produce a simplified 3D spectrogram surface using the amplitude values colected by the sampling grid (same output employed by MacLeod et al., 2013). `plot.type = "points"` will produce 3D graphs with semilandmarks as points. `plot.type = "lines"` will generate profile lines along X or Y-axis (see argument `along`). Number and space between lines are controled by arguments `skip.lines` and `space.lines`, respectively. By default: `plot.type = "surface"`
`along`	only applies when `plot.type = "lines"`. Lines along X or Y-axis (`"x"` or `"y"`). By default: `along = "x"`
`skip.lines`	only applies when `plot.type = "lines"`. How many lines to skip between each plotted line. Larger numbers imply on less lines plotted. By default: `skip.lines = 5`
`space.lines`	only applies when `plot.type = "lines"`. Controls the space between lines, which makes lines wider or narrower. Has to be a number between 0.1 and 0.9. By default: `space.lines = 0.6`
`x.length`	only applies when `samp.grid = TRUE`. 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 = 100`
`y.length`	only applies when `samp.grid = TRUE`. 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 = 70`
`lwd`	only applies when `samp.grid = TRUE` and `plot.type = "surface"`. Similarly as in `par`, intended line width for sampling grid. By default: `lwd = 0.1`
`plot.exp`	a logical. If `TRUE`, 3D spectrogram plot from `wave` object is exported and stored on the folder indicated by `store.at`. By default: `plot.exp = FALSE`
`log.scale`	only applies when `samp.grid = TRUE`. A logical. If `TRUE`, `threeDspectro` 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 = FALSE`
`cex`	only applies when `samp.grid = TRUE` and `plot.type = "points"`. Similarly as in `par`, intended size for points. By default: `cex = 0.5`
`cex.axis`	Similarly as in `par`, the magnification to be used for axis annotation. By default: `cex.axis = 0.5`
`cex.lab`	Similarly as in `par`, the magnification to be used for x and y labels. By default: `cex.lab = 0.9`
`cex.main`	Similarly as in `par`, the magnification to be used for main titles. By default: `cex.main = 1`
`store.at`	only applies when `plot.exp = TRUE`. Filepath to the folder where 3D plot will be stored. Should be presented between quotation marks. By default: `store.at = NULL` (i.e. user must specify the filepath where spectrogram plots will be stored)
`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"`
`color`	Color palette to be used for the amplitude (Z-axis). Same default as `spectro`: `color=spectro.colors(80)`. See also `Details` section.
`f`	sampling frequency of `Wave` object (in Hz). By default: `f = 44100`
`wl`	length of the window for spectrogram calculation. By default: `wl = 512`
`ovlp`	overlap between two successive windows (in %) for increased spectrogram resolution. By default: `ovlp = 70`
`dBlevel`	absolute amplitude value to be used as relative background on 3D plot. Same as `dBlevel` from `eigensound` and `align.wave`. By default: `dBlevel = 30`
`resfac`	resolution factor, in which an value > 1 will increase the resolution. Can be one value or a vector of two numbers, for the x and y values, respectively. Note: Same as in `persp3D` (`plot3D` package). By default: `resfac = 1`
`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`
`main`	main title of output plot. Should be presented between quotation marks. By default: `main = "3D spectrogram"`
`scalelab`	Similarly as `plot3D`, the label to be written on top of the color key. Should be a character string wrapped by `expression()`. By default: `scalelab = expression("Amplitude (dB)")`. See also `colkey`
`colkey`	Similarly as `plot3D`, a list with parameters for the color key (legend). By default: `colkey = list(plot = TRUE, cex.clab = 0.8, cex.axis = 1, side = 4, length = 1, width = 1, labels = TRUE, tick = TRUE, lty = 1, lwd = 1, lwd.ticks = 1)`. See also `colkey`

Details

Similarly as spectro (seewave package), any colour palette can be used to describe the amplitude (Z-axis). Some suggestions: seewave::temp.colors, seewave::spectro.colors, seewave::reverse.heat.colors, seewave::reverse.cm.colors, seewave::reverse.topo.colors, grDevices::cm.colors, grDevices::grey.colors, grDevices::heat.colors, grDevices::topo.colors.

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



# As simple as this
threeDspectro(centralis)
threeDspectro(cuvieri)
threeDspectro(kroyeri)

# Controling some arguments
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4))
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4), dBlevel=50)

# As points
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4),
              samp.grid=TRUE, plot.type="points")
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4),
              samp.grid=TRUE, plot.type="points", x.length = 20, y.length = 50)

# As lines
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4), plot.type = "lines")
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4),
              plot.type = "lines", along="y")
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4),
              plot.type = "lines", along="y", skip.lines=18, space.lines=0.8)

# Try different colors
threeDspectro(cuvieri, color=seewave::reverse.terrain.colors(80),
              samp.grid=FALSE, tlim=c(0, 0.5), flim=c(0, 4))
threeDspectro(cuvieri, color=seewave::reverse.cm.colors(80),
              samp.grid=FALSE, tlim=c(0, 0.5), flim=c(0, 4))
threeDspectro(cuvieri, color=grDevices::heat.colors(80),
              samp.grid=FALSE, tlim=c(0, 0.5), flim=c(0, 4))

# Rotation
threeDspectro(cuvieri, tlim=c(0, 0.5), flim=c(0, 4), rotate.Xaxis=40, rotate.Yaxis=50)

# Export your graph
threeDspectro(cuvieri, plot.exp=TRUE, store.at=tempdir(), tlim=c(0,0.5), flim=c(0,4))

p-rocha/SoundShape documentation built on Oct. 10, 2024, 1:29 p.m.