acoustat {seewave}

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