SoundShape (version 1.3.1)

threeDspectro: 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

Author

Pedro Rocha

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.

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.

See Also

spectro, seewave, eigensound, align.wave, persp3D, plot3D, align.wave

Useful links:

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

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

Examples

# \donttest{
# 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))
# }