acoustat: Statistics on time and frequency STFT contours

Description

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

Usage

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

Arguments

wave

an R object.

sampling frequency of wave (in Hz). Does not need to be specified if embedded in wave.

window length for the analysis (even number of points) (by default = 512).

ovlp

overlap between two successive windows (in %).

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.

Value

The function returns a list with 10 items:
time.contourthe 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.contourthe 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.P1the time initial percentile
time.Mthe time median
time.P2the time terminal percentile
time.IPRthe time interpercentile range
freq.P1the frequency initial percentile
freq.Mthe frequency median
freq.P2the frequency terminal percentile
freq.IPRthe frequency interpercentile range

Details

The principle of acoustat is as follows:

Compute the short-term Fourier transform (STFT) with usual parameters (wlfor window length,ovlpfor overlap of successive windows, andwnfor the name of window shape).
This results in a time * frequency matrix.
Compute an aggregation function (specified with the argumentaggregateset by default tosum) accross rows and columns of time * frequency matrix.)
This results in two components: (i) the time contour, and (ii) the frequency contour.
Each contour is considered as a probability mass function (PMF) and transformed into a cumulated distribution function (CDF).
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.

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. Details of the principles can be found at http://www.birds.cornell.edu/brp/research/algorithm/automated-and-robust-measurement-of-signal-features

Examples

Run this code

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")

Run the code above in your browser using DataLab

Get 50% off unlimited learning