acoustat: Statistics on time and frequency STFT contours

In seewave: Sound Analysis and Synthesis

Statistics on time and frequency STFT contours

Description

This function returns statistics based on STFT time and frequency contours.

Usage

acoustat(wave, f, channel = 1, wl = 512, ovlp = 0, wn = "hanning",
tlim = NULL, flim = NULL,
aggregate = sum, fraction = 90,
plot = TRUE, type = "l", ...)

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).
ovlp	overlap between two successive windows (in %).
wn	window name, see ftwindow (by default "hanning").
tlim	modifications of the time limits of the analysis (in s).
flim	modifications of the frequency limits of the analysis (in kHz).
aggregate	a character vector of length 1 specifying the function to be applied on the rows (time) and columns (frequency) of the STFT matrix. By default set to sum.
fraction	a numeric vector of length 1, specifying a particular fraction of the contours amplitude to be captured by the initial and terminal percentile values (in %). See details.
plot	a logical, if TRUE a two-frame plot is returned with the time and frequency contours and percentiles displayed.
type	if plot is TRUE, type of plot that should be drawn. See plot for details (by default "l" for lines).
...	other plot graphical parameters.

Details

The principle of acoustat is as follows:

1. Compute the short-term Fourier transform (STFT) with usual parameters (wl for window length, ovlp for overlap of successive windows, and wn for the name of window shape).

2. This results in a time * frequency matrix.

3. Compute an aggregation function (specified with the argument aggregate set by default to sum) accross rows and columns of time * frequency matrix.)

4. This results in two components: (i) the time contour, and (ii) the frequency contour.

5. Each contour is considered as a probability mass function (PMF) and transformed into a cumulated distribution function (CDF).

6. Measures are extracted from each CDF: median (M), initial percentile (P1) value, terminal percentile (P2) value, interpercentile range (IPR). P1, P2 and IPR are defined using a fraction parameter (fraction) that sets the percent of the contour amplitude to be captured by the initial and terminal percentile values. A fraction of 50% would result in the familiar quartiles and interquartile range. An energy fraction of 80% would return the 10th and 90th percentile values, and the width of the range in between.

Value

The function returns a list with 10 items:

time.contour	the time contour as a two-column matrix, the first colum being time (s) and the second colum being the amplitude probability mass function (no scale).
freq.contour	the frequency contour as a two-column matrix, the first colum being frequency (kHz) and the second colum being the amplitude probability mass function (no scale).
time.P1	the time initial percentile
time.M	the time median
time.P2	the time terminal percentile
time.IPR	the time interpercentile range
freq.P1	the frequency initial percentile
freq.M	the frequency median
freq.P2	the frequency terminal percentile
freq.IPR	the frequency interpercentile range

Note

acoustat was originally developped in Matlab language by Kurt Fristrup and XXXX Watkins (1992) .
The R function was kindly checked by Kurt Fristrup.

Author(s)

Jerome Sueur

References

Fristrup, K. M. and Watkins, W. A. 1992. Characterizing acoustic features of marine animal sounds. Woods Hole Oceanographic Institution Technical Report WHOI-92-04.

See Also

meanspec, specprop

Examples

data(tico)
note <- cutw(tico, from=0.5, to=0.9, output="Wave")
## default setting
acoustat(note)
## change the percentile fraction
acoustat(note, fraction=50)
## change the STFT parameters
acoustat(note, wl=1024, ovlp=80)
## change the function to compute the aggregate contours
## standard deviation instead of sum   
acoustat(note, aggregate=sd)
## direct time and frequency selection     
acoustat(tico, tlim=c(0.5,0.9), flim=c(3,6))
## some useless graphical changes
acoustat(note, type="o", col="blue") 

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