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, complex = FALSE, norm = TRUE, fftw = FALSE,
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",
cexlab = 1, cexaxis = 1, 
tlab = "Time (s)",
flab = "Frequency (kHz)",
alab = "Amplitude",
scalelab = "Amplitude(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,
...)
wave{an R object.}     
  f{sampling frequency of wave (in Hz). Does not need to
    be specified if embedded in wave.}  
  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 %).}
  complex{if TRUE the STFT will be returned as complex
  numbers.}  
  norm{if TRUE the STFT is normalised (i. e. scaled) by its maximum.}
  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" and "D" 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).}
  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.}
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.
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. 
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.}
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
ggspectro, 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 (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=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
