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 withu(), 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()andsigma_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 signalx_sample_freq. Since the output is generated by averaging over an integer number of input samples, the actual output sampling rate isx_sample_freq / k, wherek = floor(x_sample_freq / y_sample_freq). It is equal to or slightly higher thany_sample_freqand 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: from2 * x_sample_freq / length(x)up to the Nyquist frequencyx_sample_freq / 2. A frequency-valued number, generated withu(), 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_scaleargument. 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, increasingn_freqsbeyond 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 increasen_freqsand perform appropriate averaging afterwards: the output signal will show improved response.- freq_scale
One of
"log"(default) or"linear": should then_freqsfrequencies be distributed logarithmically or linearly betweenfreq_beginandfreq_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) orFALSE. Boundary effects can result in nonphysical artifacts. Ifrm_coi = TRUE, those are effectively removed by setting corresponding values toNA. 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 ifrm_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()returnsFALSE, 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
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