% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/wavelet.R
\name{wavelet}
\alias{wavelet}
\alias{wavelet_kernels}
\alias{morlet_wavelet}
\alias{wavelet_cycles_suggest}
\title{'Morlet' wavelet transform (Discrete)}
\usage{
wavelet_kernels(freqs, srate, wave_num)

morlet_wavelet(
  data,
  freqs,
  srate,
  wave_num,
  precision = c("float", "double"),
  trend = c("constant", "linear", "none"),
  signature = NULL,
  segment_length = NULL,
  ...
)

wavelet_cycles_suggest(
  freqs,
  frequency_range = c(2, 200),
  cycle_range = c(3, 20)
)
}
\arguments{
\item{freqs}{frequency in which \code{data} will be projected on}

\item{srate}{sample rate, number of time points per second}

\item{wave_num}{desired number of cycles in wavelet kernels to
balance the precision in time and amplitude (control the
smoothness); positive integers are strongly suggested}

\item{data}{numerical vector such as analog voltage signals}

\item{precision}{the precision of computation; choices are
\code{'float'} (default) and \code{'double'}.}

\item{trend}{choices are \code{'constant'}: center the signal at zero;
\code{'linear'}: remove the linear trend; \code{'none'} do nothing}

\item{signature}{signature to calculate kernel path to save, internally used}

\item{segment_length}{optional positive integer; when provided, long signals
are processed in overlapping segments of this length (in samples) using
batched \code{\link{mvfftw_c2c}} convolutions instead of a single full-length
FFT. This dramatically reduces peak memory and FFT cost for long recordings
(e.g. multi-hour). Must be strictly greater than the longest wavelet kernel
length (the kernel at the lowest frequency); otherwise an error is raised.
Default is \code{NULL}, which uses the legacy single-shot path. When
\code{segment_length >= length(data)} the function silently falls back to
the legacy path. Results match the legacy path on the interior of the
signal up to floating-point error; the first/last
\code{ceiling(max_kernel_len/2)} samples may differ near the global
boundaries (both implementations have boundary artifacts there).}

\item{...}{further passed to \code{\link{detrend}};}

\item{frequency_range}{frequency range to calculate, default is 2 to 200}

\item{cycle_range}{number of cycles corresponding to \code{frequency_range}.
For default frequency range (2 - 200), the default \code{cycle_range} is
3 to 20. That is, 3 wavelet kernel cycles at 2 Hertz, and 20 cycles at 200
Hertz.}
}
\value{
\code{wavelet_kernels} returns wavelet kernels to be
used for wavelet function; \code{morlet_wavelet} returns a file-based array
if \code{precision} is \code{'float'}, or a list of real and imaginary
arrays if \code{precision} is \code{'double'}
}
\description{
Transform analog voltage signals with 'Morlet'
wavelets: complex wavelet kernels with \eqn{\pi/2} phase
differences.
}
\examples{

\donttest{

# generate sine waves
time <- seq(0, 3, by = 0.01)
x <- sin(time * 20*pi) + exp(-time^2) * cos(time * 10*pi)

plot(time, x, type = 'l')

# freq from 1 - 15 Hz; wavelet using float precision
freq <- seq(1, 15, 0.2)
coef <- morlet_wavelet(x, freq, 100, c(2,3))

# to get coefficients in complex number from 1-10 time points
coef[1:10, ]

# power
power <- Mod(coef[])^2

# Power peaks at 5Hz and 10Hz at early stages
# After 1.0 second, 5Hz component fade away
image(power, x = time, y = freq, ylab = "frequency")

# wavelet using double precision
coef2 <- morlet_wavelet(x, freq, 100, c(2,3), precision = "double")
power2 <- (coef2$real[])^2 + (coef2$imag[])^2

image(power2, x = time, y = freq, ylab = "frequency")

# The maximum relative change of power with different precisions
max(abs(power/power2 - 1))

# display kernels
freq <- seq(1, 15, 1)
kern <- wavelet_kernels(freq, 100, c(2,3))
print(kern)

plot(kern)

}

}
