spectro: 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, wl = 512, wn = "hanning", zp = 0,
ovlp = 0, dB = "max0", dBref = NULL, plot = TRUE,
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",
plot.title = title(main = "", xlab = "Time (s)", 
ylab = "Frequency (kHz)"), scalelab = "Amplitude(dB)",
scalefontlab = 1, scalecexlab =0.75,
axisX = TRUE, axisY = TRUE, tlim = NULL, trel = TRUE,
flim = NULL, flimd = NULL, listen=FALSE,
...)
wave{a vector, a matrix (first column),
	an object of class ts, Sample (left channel),
	or Wave (left channel).}
  f{sampling frequency of wave (in Hz).
  Does not need to be specified if wave is an object of class ts,
	Sample, or Wave.}  wl{window length for the analysis
    (even number of points). (by default = 512)}
  zp{zero-padding (even number of points), see Details.}
  ovlp{overlap between two successive windows (in %).}
  dB{a character string specifying the type dB to return: "max0"
	(default) for a maximum dB value at 0, "A", "B", "C" and "D" 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.}
  wn{window name, see ftwindow (by default "hanning").}
  plot{logical, if TRUE plots the spectrogram
        (by default TRUE).}
  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.}  
  plot.title{statements which add titles to the plot.}
  scalelab{amplitude scale label.}
  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.} 
  flimd{dynamic modifications of the frequency Y-axis limits. New wl
      and ovlp arguments are applied to increase time/frequency resolution.}
  listen{if TRUE the sound is played back (by default FALSE).}
  ...{other contour and oscillo
    graphical parameters.}
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, 
rev.gray.colors.1,
rev.gray.colors.2, rev.heat.colors,
rev.terrain.colors, rev.topo.colors,
rev.cm.colors corresponding to the reverse of heat.colors, 
terrain.colors, topo.colors, cm.colors.
Use locator to identify  points.
If plot is FALSE, this function returns a matrix. Each column
corresponds to a Fourier transform of length wl/2.
Hopp, S. L., Owren, M. J. and Evans, C. S. (Eds) 1998. Animal acoustic 
communication. Springer, Berlin, Heidelberg.
[object Object],[object Object]
This function is based on fft, contour and
filled.contour
spectro3D, dynspec, wf, 
oscillo, dBscale, fft.
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 (20 microPa)
spectro(tico,f=22050, dBref=2*10e-5)
# 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, ylim=c(2,6))
spectro(tico,f=22050, ylimd=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=rev.terrain.colors)
# black and white spectrogram 
spectro(pellu2,f=22050,ovlp=85,zp=16,
    palette=rev.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=rev.cm.colors,osc=TRUE,colwave="orchid1") 
spectro(pellu2,f=22050,ovlp=85,zp=16,osc=TRUE,palette=rev.heat.colors,
colbg="black",colgrid="white", colwave="white",colaxis="white",collab="white")
dplot
ts
Description

Usage

Arguments
