Fast continuous wavelet transform

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 the continuous wavelet transform, i.e. a real valued positive matrix with a time and a frequency dimension.

Usage

fcwt(
  x,
  x_sample_freq,
  sigma = 2 * pi,
  y_sample_freq = 3/sigma_res(sigma, freq_end)$time,
  freq_begin = 2 * x_sample_freq/length(x),
  freq_end = x_sample_freq/2,
  n_freqs = 3 * ceiling(log(du(freq_end/freq_begin), base = 1 +
    sigma_freq_res_rel(sigma))),
  freq_scale = c("log", "linear"),
  rm_coi = TRUE,
  n_threads = 2L
)

Arguments

x

Real-valued time series. The time steps are assumed to be evenly spaced.

x_sample_freq

Sampling rate of input time series x. 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. Expects either a value with frequency units, generated with u(), or a pure number, in which case it is interpreted in units of 'Hertz'.

sigma

Sets a dimensionless parameter \(\Sigma\) controlling the wavelet spread. Changing this parameter adjusts the time/frequency uncertainty balance, \(\Delta t = 4 \frac{\Sigma}{f}\), \(\Delta f = 4 \frac{f}{2\pi \Sigma}\). Larger (lower) value of sigma corresponds to a better (worse) frequency resolution and a worse (better) time resolution.

For more information, see vignette("sigma", package = "fCWTr")).

Defaults to \(2\pi\). Note that there is not really a natural choice for sigma, it depends on the use case. So the default choice can very well be quite a bad choice (it probably is for audio data).

y_sample_freq

Sampling rate of output time series, in frequency units (see u()). The default value is set so that it aligns with the physical time resolution of the highest frequency modes. The maximum allowed sampling rate is the sampling rate of the input signal x_sample_freq.

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. A frequency-valued number, generated with u(), or a pure number, that is interpreted in units of 'Hertz'.

n_freqs

Number of frequency bins generated by the CWT. The frequencies are linearly or logarithmically distributed, depending on the freq_scale argument. Computation time increases when raising the number of frequency bins. The default number is chosen such that the frequency bandwidths are of the size of the physical frequency resolutions in case of a logarithmic scale. In some sense this value constitutes the "physical" limit. However, increasing n_freqs beyond this limit can still make sense: If we have a signal of a precise frequency, and the probing frequency band is not exactly aligned, the output signal will be dampened. In this case it can be useful to increase n_freqs and perform appropriate averaging afterwards: the output signal will show improved response.

freq_scale

( "log" | "linear" ) Should the frequency scale be linear or logarithmic? "linear" / "log" for linear / logarithmic. The default scale is logarithmic since differences on a logarithmic scale are proportional to the frequency uncertainties. In this sense, the logarithmic frequency scale is actually the natural scale for the continuous wavelet transform.

rm_coi

( TRUE | FALSE ) Boundary effects can result in nonphysical artifacts. If rm_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, \(\Delta t = \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 \(\Delta t /2\). Values that fall into that range are removed if rm_coi = TRUE.

n_threads

Number of threads used by the computation, if supported by your platform. Defaults to 2 threads (to accommodate CRAN requirements). If openmp_enabled() returns FALSE, this argument is ignored, and only a single thread is used.

Value

The spectogram, a numeric real-valued matrix with dimensions dim = c(length(x), n_freqs), curated with some additional properties. This matrix is wrapped into a S3-class fcwtr_scalogram so that plotting and coercion functions can be used conveniently. Use as.matrix() to strip the curated information. Or use as.data.frame() to convert to another data format.

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). doi:10.1038/s43588-021-00183-z

Examples