fcwt: Fast continuous wavelet transform

In fCWTr: Fast Continuous Wavelet Transform

Fast continuous wavelet transform

Description

The core function of this package making use of the fCWT library. It processes an input signal in form of a real valued numeric vector interpreted as an evenly spaced time series and returns the absolute values of a spectogram, i.e. a graph with a time and a frequency dimension.

Usage

fcwt(
  signal,
  sample_freq,
  n_freqs,
  freq_begin = 2 * sample_freq/length(signal),
  freq_end = sample_freq/2,
  sigma = 1,
  remove_coi = TRUE,
  n_threads = 2L
)

Arguments

signal	Real-valued time series. The time steps are assumed to be evenly spaced.
sample_freq	Sampling rate of input time series. This number primarily establishes a connection to physical units which is used in other frequency definitions as well as the units of the output data.
n_freqs	Number of frequency bins generated by the CWT. The frequencies are linearly distributed. Computation time increases when raising the number of frequency bins.
freq_begin, freq_end	Optionally specifies the frequency range ⁠[freq_end, freq_begin]⁠. If not specified the maximal meaningful frequency range, depending on the input signal, is taken. The range and sample_freq need to be specified in the same units.
sigma	Sets a dimensionless parameter modifying the wavelet spread which in the time-domain is roughly given by \Sigma_t \sim \sqrt{2} \frac{\sigma}{f}. Changing this parameter adjusts the time/frequency uncertainty balance. Defaults to 1. Larger (lower) value of sigma corresponds to a better (worse) frequency resolution and a worse (better) time resolution.
remove_coi	Boundary effects can result in nonphysical artifacts. If remove_coi = TRUE, those are effectively removed by setting corresponding values to NA. We define the essential support of the (Gaussian) wavelet to be four times its standard deviation, 4 \Sigma_t = 2 * \sqrt{2} \frac{\sigma}{f}, and so a wavelet touches the boundary if the distance of the center of the wavelet to the boundary is less then 4 \Sigma_t. Values that fall into that range are removed if remove_coi = TRUE.
n_threads	Number of threads used by the computation, if supported by your platform. Defaults to 2 threads (to accomodate CRAN requirements).

Details

The wavelet used in this calculation is the so called Morlet wavelet, a sinusoidal wave modulated by a Gaussian whose spread is controlled by the argument sigma.

See the original paper Arts, L.P.A., van den Broek, E.L. The fast continuous wavelet transformation (fCWT) for real-time, high-quality, noise-resistant time–frequency analysis. Nat Comput Sci 2, 47–58 (2022). \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1038/s43588-021-00183-z")}

Value

The spectogram, a numeric real-valued matrix with dimensions dim = c(length(signal), n_freqs). This matrix is wrapped into a S3-class fcwtr_scalogram so that plotting and coercion functions can be used conveniently.

Examples

ts_sin_440 <- sin((1:5000) * 2 * pi * 440 / 44100)

res <-
  fcwt(
    ts_sin_440,
    sample_freq = 44100,
    freq_begin = 50,
    freq_end = 1000,
    n_freqs = 10,
    sigma = 5
  )

fCWTr documentation built on June 22, 2024, 10:20 a.m.