R: 3D-spectrogram of a time wave

spectro3D {seewave}

R Documentation

3D-spectrogram of a time wave

Description

This function returns a three-dimension spectrographic representation of a time wave. The function corresponds to short-term Fourier transform.

Usage

spectro3D(wave, f, channel = 1, wl = 512, wn = "hanning", zp = 0,
ovlp = 0, noisereduction = FALSE, norm = TRUE, correction = "none", fftw = FALSE,
dB = "max0", dBref = NULL, plot = TRUE,
magt = 10, magf = 10, maga = 2,
palette = reverse.terrain.colors)

Arguments

`wave`	an R object.
`f`	sampling frequency of `wave` (in Hz). Does not need to be specified if embedded in `wave`.
`channel`	channel of the R object, by default left channel (1).
`wl`	length of the window for the analysis (even number of points).
`wn`	window name, see `ftwindow` (by default `"hanning"`).
`zp`	zero-padding (even number of points), see `Details`.
`ovlp`	overlap between two successive windows (in % ).
`noisereduction`	a logical, if `TRUE` a noise reduction is applied.
`norm`	if `TRUE` the STFT is normalised (i. e. scaled) by its maximum.
`correction`	a character vector of length 1 to apply an amplitude ("amplitude") or an energy ("energy") correction to the FT window. This argument is useful only when one wish to obtain absolute values that is when `norm=FALSE`, `scaled=FALSE`, and `PMF=FALSE`. By default no correction is applied ("none").
`fftw`	if `TRUE` calls the function `FFT` of the library `fftw`. See Notes of the `spectro`.
`dB`	a character string specifying the type dB to return: "max0" for a maximum dB value at 0, "A", "B", "C", "D", and "ITU" for common dB weights.
`dBref`	a dB reference value when `dB` is `TRUE`. `NULL` by default but should be set to 2*10e-5 for a 20 microPa reference.
`plot`	logical, if `TRUE` plots the spectrogram (by default `TRUE`).
`magt`	magnification of the time axis.
`magf`	magnification of the frequency axis.
`maga`	magnification of the amplitude axis.
`palette`	a color palette function to be used to assign colors in the plot, see `Details`.

Details

Following Heisenberg uncertainty principle, the short-term Fourier transform cannot be precised in both time and frequency. The temporal and frequency precisions of the function are actually dependent of the wl value. Choosing a high wl value will increase the frequency resolution but reduce the temporal one, and vice versa. The frequency precision is obtained by calculating the ratio f/wl, and the temporal precision is obtained by calculating the reverse ratio wl/f. This problem can be reduced in some way with zp that adds 0 values on both sides of the analysis window. This increases frequency resolution without altering time resolution.
Any colour palette can be used. In particular, it is possible to use other palettes coming with seewave: reverse.gray.colors.1, reverse.gray.colors.2, spectro.colors, temp.colors, reverse.heat.colors, reverse.cm.colors, reverse.topo.colors, corresponding to the reverse of heat.colors,topo.colors, cm.colors.
Use magt, magf and maga to resize the plot.

Value

This function returns a list of three items:

`time`	a numeric vector corresponding to the time axis.
`freq`	a numeric vector corresponding to the frequency axis.
`amp`	a numeric matrix corresponding to the amplitude values. Each column is a Fourier transform of length `wl`/2.

Note

This function requires rgl and is based on fft. See examples of spectro for analysis arguments (wl,zp, ovlp).

Author(s)

Jerome Sueur sueur@mnhn.fr and Caroline Simonis csimonis@mnhn.fr.

Examples

## Not run: 
require(rgl)
data(tico)
spectro3D(tico,f=22050,wl=512,ovlp=75,zp=16,maga=4,palette=reverse.terrain.colors)
# linear amplitude scale without a normisation of the STFT matrix
# time and frequency scales need to be dramatically amplified
spectro3D(tico, norm=FALSE, dB=NULL, magt=100000, magf=100000)

## End(Not run)

[Package seewave version 2.1.6 Index]