env {seewave}

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.

See Also

oscillo,hilbert

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)