Performs a fast continuous wavelet transform on long sequences by sequentially
processing chunks (batches) of the input signal.
This is only useful for very long signals that cannot be processed by
fcwt() in one go.
It should not be used on short signals since boundary artefacts are
automatically discarded (and those potentially dominate for short signals).
Usage
fcwt_batch(
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"),
max_batch_size = default_max_batch_size(x_sample_freq, y_sample_freq, n_freqs),
n_threads = 2L,
progress_bar = FALSE
)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.- max_batch_size
The maximal batch size (number of input samples) that is used for splitting up the input sequence. This limits the memory that is needed while processing a batch, which is roughly $$50 + 16 \cdot \frac{n_{freqs}}{k}$$ bytes per input sample, where \(k = x_{sample\_freq} / y_{sample\_freq}\) is the number of input samples that are averaged into one output sample: about 50 bytes are needed for the transform itself, the rest for the output of the batch (and a temporary copy of it). The default is the largest power of two for which this amounts to at most about 500 MB. (The Fourier transforms are fastest for powers of two, other sizes are zero-padded to the next power of two, which also increases the memory needed for the transform.)
Independent of the batch size, the outputs of all batches are kept and finally joined, which needs about twice the memory of the final result.
The actual batch size is the largest batch size that is not larger than
max_batch_sizeand compatible with the requestedy_sample_freq. Each batch loses about4 * sigma * x_sample_freq / freq_beginsamples to boundary effects, so for low values offreq_begin, increase the batch size as far as your memory allows (see also the loss ratio reported withprogress_bar = 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.- progress_bar
Monitoring progress can sometimes be useful when performing time consuming operations. Setting
progress_bar = TRUEenables printing a progress bar to the console, printing the "loss ratio" and the number of batches. The loss ratio is a number between 0 and 1 and indicates how much of the batch computation has to be thrown away due to boundary artefacts. The higher the batch size the smaller the loss ratio will be. Defaults toFALSE.
Value
The scalogram, a numeric real-valued matrix with dimensions roughly
dim ~ c(length(x) * y_sample_freq / x_sample_freq, n_freqs).
The exact length of the output depends on boundary effect details.
This matrix is wrapped into a S3-class "fcwtr_scalogram" so that plotting and
coercion functions can be used conveniently.
Details
fcwt() computes the result frequency by frequency and averages over time
on the fly (see its y_sample_freq argument), so the size of its output
is usually not the limiting factor. However, it performs Fourier transforms
over the whole input signal. This requires memory proportional to the
signal length (several single-precision complex copies of the signal,
zero-padded to the next power of two), and the signal length is limited to
\(2^{30}\) samples. For instance, a recording of 24 hours at a sampling
rate of 44100 Hz has about \(3.8 \cdot 10^9\) samples.
This function splits up the input sequence into overlapping batches,
processes each batch separately with fcwt(), removes the boundary
artefacts of each batch, and joins the outputs together.
Attention: In contrast to fcwt() boundary artefacts are automatically removed,
so some information at the beginning and the end of the
sequence is lost. (The amount depends on the lowest frequency freq_begin,
since low-frequency wavelets are spread out the most in time.)
Examples
fcwt_batch(
ts_sin_sin,
x_sample_freq = u(44.1, "kHz"),
sigma = 10,
y_sample_freq = u(100, "Hz"),
freq_begin = u(100, "Hz"),
freq_end = u(11000, "Hz"),
n_freqs = 30
)
#> _Scalogram_
#> * (Time/Frequency) dimension: ( 60 , 30 )
#> * Sampling rate: 0.1 [kHz]
#> * Frequency scale: 100 [Hz] - 11000 [Hz], log
#> * Time offset: 200 [ms]
#> * Sigma: 10
#> o Time resolution at 100 [Hz] : 400 [ms]
#> o Time resolution at 11000 [Hz] : 3.636364 [ms]
#> o Relative frequency resolution: 0.06366198
#> * Time/frequency matrix summary
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> 1.000e-08 4.060e-06 8.440e-06 8.707e-03 2.034e-05 9.055e-01