spectro: 2D-spectrogram of a time wave

In seewave: Sound Analysis and Synthesis

2D-spectrogram of a time wave

Description

This function returns a two-dimension spectrographic representation of a time wave. The function corresponds to short-term Fourier transform. An amplitude contour plot can be overlaid.

Usage

spectro(wave, f, channel = 1, wl = 512, wn = "hanning", zp = 0,
ovlp = 0, noisereduction = NULL, fastdisp = FALSE,
complex = FALSE, norm = TRUE, correction="none",
fftw = FALSE, dB = "max0", dBref = NULL, plot = TRUE,
flog = FALSE, grid = TRUE, osc = FALSE, scale = TRUE, cont = FALSE,
collevels = NULL, palette = spectro.colors,
contlevels = NULL, colcont = "black",
colbg = "white", colgrid = "black",
colaxis = "black", collab="black",
cexlab = 1, cexaxis = 1, 
tlab = "Time (s)",
flab = "Frequency (kHz)",
alab = "Amplitude",
scalelab = "Amplitude\n(dB)",
main = NULL,
scalefontlab = 1, scalecexlab =0.75,
axisX = TRUE, axisY = TRUE, tlim = NULL, trel = TRUE,
flim = NULL, flimd = NULL,
widths = c(6,1), heights = c(3,1),
oma = rep(0,4),
listen=FALSE,
...)

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	window length for the analysis (even number of points) (by default = 512).
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 numeric vector of length 1, if 1 a noise reduction is applied along the rows of the spectrogram, if 2 a noise reduction applied along the columns. See Details.
fastdisp	faster graphic display for long wave. The spectrogram/oscillogram is displayed/saved faster in the graphic device/ graphic file when set to TRUE, with a cost on graphical resolution.
complex	if TRUE the STFT will be returned as complex numbers.
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 each FT window. This argument is useful only when one wish to obtain absolute values that is when norm=FALSE. By default no correction is applied ("none").
fftw	if TRUE calls the function FFT of the library fftw. See Notes.
dB	a character string specifying the type dB to return: "max0" (default) for a maximum dB value at 0, "A", "B", "C", "D", and "ITU" for common dB weights. If set to NULL, then a linear scale is used.
dBref	a dB reference value. 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).
flog	a logical to plot the frequency on a logarithmic scale.
grid	logical, if TRUE plots a y-axis grid (by default TRUE).
osc	logical, if TRUE plots an oscillogram beneath the spectrogram (by default FALSE).
scale	logical, if TRUE plots a dB colour scale on the right side of the spectrogram (by default TRUE).
cont	logical, if TRUE overplots contour lines on the spectrogram (by default FALSE).
collevels	a set of levels which are used to partition the amplitude range of the spectrogram (in dB).
palette	a color palette function to be used to assign colors in the plot, see Details.
contlevels	a set of levels which are used to partition the amplitude range for contour overplot (in dB).
colcont	colour for cont plotting.
colbg	background colour.
colgrid	colour for grid plotting.
colaxis	color of the axes.
collab	color of the labels.
cexlab	size of the labels.
cexaxis	size of the axes.
tlab	label of the time axis.
flab	label of the frequency axis.
alab	label of the amplitude axis.
scalelab	amplitude scale label.
main	label of the main title.
scalefontlab	font of the amplitude scale label.
scalecexlab	cex of the amplitude scale label.
axisX	logical, if TRUE plots time X-axis (by default TRUE).
axisY	logical, if TRUE plots frequency Y-axis (by default TRUE).
tlim	modifications of the time X-axis limits.
trel	time X-axis with a relative scale when tlim is not null, i.e. relative to wave.
flim	modifications of the frequency Y-axis limits (in kHz).
flimd	dynamic modifications of the frequency Y-axis limits. New wl and ovlp arguments are applied to increase time/frequency resolution.
widths	a vector of length 2 to control the relative widths of columns on the device when scale is TRUE.
heights	a vector of length 2 to control the relative heights of rows on the device when osc is TRUE.
oma	a vector of length 4 to control the size of outer margins when either scale or osc is TRUE.
listen	if TRUE the sound is played back (by default FALSE).
...	other contour and oscillo graphical parameters.

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: temp.colors, reverse.gray.colors.1, reverse.gray.colors.2, reverse.heat.colors, reverse.terrain.colors, reverse.topo.colors, reverse.cm.colors corresponding to the reverse of heat.colors, terrain.colors, topo.colors, cm.colors.
Use locator to identify points. The noise reduction using the argument noisereduction is an image filter, not a signal filter. The principle consists in subtracting each spectrogram row or column by its median. Noise reduction alters energy conservation, it should then be used for visual display only.

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 or a complex matrix corresponding to the amplitude values. Each column is a Fourier transform of length wl/2.

Note

The argument fftw can be used to try to speed up process time. When set to TRUE, the Fourier transform is computed through the function FFT of the package fftw. This pacakge is a wrapper around the fastest Fourier transform of the free C subroutine library FFTW (http://www.fftw.org/). FFT should be then installed on your OS.

Note

This function is based on fft, contour and filled.contour

Author(s)

Jerome Sueur and Caroline Simonis.

References

Hopp, S. L., Owren, M. J. and Evans, C. S. (Eds) 1998. Animal acoustic communication. Springer, Berlin, Heidelberg.

See Also

ggspectro, spectro3D, lts, dynspec, wf, oscillo, dBscale, fft.

Examples

## Not run: 
data(tico)
data(pellucens)
# simple plots
spectro(tico,f=22050)
spectro(tico,f=22050,osc=TRUE)
spectro(tico,f=22050,scale=FALSE)
spectro(tico,f=22050,osc=TRUE,scale=FALSE)
# change the dB scale by setting a different dB reference value (20microPa)
spectro(tico,f=22050, dBref=2*10e-5)
# unnormalised spectrogram with a linear amplitude scale
spectro(tico, dB=NULL, norm=FALSE, scale=FALSE)
# manipulating wl
op<-par(mfrow=c(2,2))
spectro(tico,f=22050,wl=256,scale=FALSE)
title("wl = 256")
spectro(tico,f=22050,wl=512,scale=FALSE)
title("wl = 512")
spectro(tico,f=22050,wl=1024,scale=FALSE)
title("wl = 1024")
spectro(tico,f=22050,wl=4096,scale=FALSE)
title("wl = 4096")
par(op)
# vertical zoom using flim
spectro(tico,f=22050, flim=c(2,6))
spectro(tico,f=22050, flimd=c(2,6))
# a full plot
pellu2<-cutw(pellucens,f=22050,from=1,plot=FALSE)
spectro(pellu2,f=22050,ovlp=85,zp=16,osc=TRUE,
    cont=TRUE,contlevels=seq(-30,0,20),colcont="red",
    lwd=1.5,lty=2,palette=reverse.terrain.colors)
# black and white spectrogram 
spectro(pellu2,f=22050,ovlp=85,zp=16,
    palette=reverse.gray.colors.1)
# colour modifications
data(sheep)
spectro(sheep,f=8000,palette=temp.colors,collevels=seq(-115,0,1))
spectro(pellu2,f=22050,ovlp=85,zp=16,
palette=reverse.cm.colors,osc=TRUE,colwave="orchid1") 
spectro(pellu2,f=22050,ovlp=85,zp=16,osc=TRUE,palette=reverse.heat.colors,
colbg="black",colgrid="white", colwave="white",colaxis="white",collab="white")

## End(Not run)

seewave documentation built on Oct. 19, 2023, 5:07 p.m.