R: Amplitude envelope of a time wave

env {seewave}

R Documentation

Amplitude envelope of a time wave

Description

This function returns the absolute or Hilbert amplitude envelope of a time wave.

Usage

env(wave, f, channel = 1, envt = "hil", 
msmooth = NULL, ksmooth = NULL, ssmooth = NULL,
asmooth = NULL,
fftw = FALSE, norm = FALSE,
plot = TRUE, k = 1, j = 1, ...)

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).
`envt`	the type of envelope to be returned: either "abs" for absolute amplitude envelope or "hil" for Hilbert amplitude envelope. See Details section.
`msmooth`	a vector of length 2 to smooth the amplitude envelope with a mean sliding window. The first component is the window length (in number of points). The second component is the overlap between successive windows (in %). See examples.
`ksmooth`	kernel smooth via `kernel`. See examples.
`ssmooth`	length of the sliding window used for a sum smooth.
`asmooth`	length of the sliding window used for an autocorrelation smooth.
`fftw`	if `TRUE` calls the function `FFT` of the library `fftw` for faster computation for the Hilbert amplitude envelope (`envt="hil"`) and/or for kernell smoothing (`ksmooth`).
`norm`	a logical, if `TRUE` the amplitude of the envelope is normalised between 0 and 1.
`plot`	logical, if `TRUE` returns a plot of `wave` envelope (by default `TRUE`).
`k`	number of horizontal sections when `plot` is `TRUE` (by default =1).
`j`	number of vertical sections when `plot` is `TRUE` (by default =1).
`...`	other `oscillo` graphical parameters.

Details

When envt is set as "abs", the amplitude envelope returned is the absolute value of wave.
When envt is set as "hil", the amplitude envelope returned is the modulus (Mod) of the analytical signal of wave obtained through the Hilbert transform (hilbert).

Value

Data are returned as one-column matrix when plot is FALSE.

Note

Be aware that smoothing with either msmooth or ksmooth changes the original number of points describing wave.

Author(s)

Jerome Sueur. Implementation of 'fftw' argument by Jean Marchal and Francois Fabianek. Implementation of 'asmooth' by Thibaut Marin-Cudraz.

Examples

data(tico)
# Hilbert amplitude envelope
env(tico)
# absolute amplitude envelope
env(tico, envt="abs")
# smoothing with a 10 points and 50% overlaping mean sliding window
env(tico, msmooth=c(10,50))
# smoothing kernel
env(tico, ksmooth=kernel("daniell",10))
# sum smooth
env(tico, ssmooth=50)
# autocorrelation smooth
env(tico, asmooth=50)
# overplot of oscillographic and envelope representations
oscillo(tico)
par(new=TRUE)
env(tico, colwave=2)

[Package seewave version 2.1.6 Index]