Skip to contents

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'. It does not need to be an integer.

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). See sigma_from_time_res(), sigma_from_freq_res() and sigma_from_freq_res_rel() to determine sigma from resolution requirements.

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. Since the output is generated by averaging over an integer number of input samples, the actual output sampling rate is x_sample_freq / k, where k = floor(x_sample_freq / y_sample_freq). It is equal to or slightly higher than y_sample_freq and is stored in the result.

freq_begin, freq_end

Optionally specifies the frequency range [freq_begin, freq_end] (both inclusive). If not specified the maximal meaningful frequency range, depending on the input signal, is taken: from 2 * x_sample_freq / length(x) up to the Nyquist frequency x_sample_freq / 2. 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

One of "log" (default) or "linear": should the n_freqs frequencies be distributed logarithmically or linearly between freq_begin and freq_end? 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 (default) or 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 at frequency \(f\) to be four times its standard deviation \(\Sigma / f\), i.e. \(\Delta t = 4 \frac{\Sigma}{f}\), and so a wavelet touches the boundary if the distance of the center of the wavelet to the boundary is less than \(\Delta t / 2\). Values that fall into that range (the "cone of influence") 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 scalogram, a numeric real-valued matrix with a time (rows) and a frequency (columns) dimension, curated with some additional properties. Its dimensions are c(ceiling(length(x) / k), n_freqs), where k is the number of input samples averaged per output sample (see y_sample_freq; k = 1 if y_sample_freq = x_sample_freq). The columns are ordered from the highest (freq_end) to the lowest (freq_begin) frequency.

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

See also

Examples

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

fcwt(
  ts_sin_440,
  x_sample_freq = u(44.1, "kHz"),
  sigma = 5,
  freq_begin = u(50, "Hz"),
  freq_end = u(1000, "Hz"),
  n_freqs = 10
)
#> _Scalogram_
#> * (Time/Frequency) dimension:  ( 18 , 10 )
#> * Sampling rate: 0.15 [kHz]
#> * Frequency scale: 50 [Hz] - 1000 [Hz], log
#> * Time offset: 0 [s] 
#> * Sigma: 5
#>   o Time resolution at  50 [Hz] :  400 [ms] 
#>   o Time resolution at  1000 [Hz] :  20 [ms] 
#>   o Relative frequency resolution:  0.127324 
#> * Time/frequency matrix summary
#>      Min.   1st Qu.    Median      Mean   3rd Qu.      Max.       NAs 
#> 3.366e-06 1.305e-05 1.412e-04 2.837e-03 2.391e-03 4.841e-02       114