Skip to contents

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 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.

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_size and compatible with the requested y_sample_freq. Each batch loses about 4 * sigma * x_sample_freq / freq_begin samples to boundary effects, so for low values of freq_begin, increase the batch size as far as your memory allows (see also the loss ratio reported with progress_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() returns FALSE, 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 = TRUE enables 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 to FALSE.

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.)

See also

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