improve fcwt_batch documentation, and change parameter order slightly.

R/fcwt.R

@@ -75,6 +75,8 @@
 #'  the curated information. Or use [as.data.frame()] to convert to another
 #'  data format.
 #'
+#' @seealso [fcwt_batch()]
+#'
 #' @examples
 #' ts_sin_440 <- sin((1:5000) * 2 * pi * 440 / 44100)
 #'

R/fcwt_batch.R

@@ -2,7 +2,7 @@
 #'
 #' Performs a fast continuous wavelet transform on long sequences by sequentially
 #' processing junks of the input signal and keeping only low-resolution output
-#' data to preserve memory.
+#' data by averaging to preserve memory.
 #' This is only useful for very long signals whose output does not fit into
 #' the available memory as a whole.
 #' It should not be used on short signals since boundary artefacts are
@@ -27,28 +27,34 @@
 #' This function splits up the input sequence into batches, processes each
 #' batch separately, reduces the time resolution, and adds the outputs together.
 #'
-#' Attention: In contrast to `fcwt()` boundary artefacts are automatically removed,
-#' so some high frequency information at the beginning and the end of the
+#' 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 minimal frequency captured `min_freq`.)
 #'
 #' @param max_batch_size
 #'  The maximal batch size that is used for splitting up the input sequence.
 #'  This limits the maximal memory that is used. Defaults to roughly 1GB, being
 #'  conservative and taking into account that R might make copies when further
 #'  processing it.
-#'  The actual batch size depends on the requested `time_resolution`.
+#'  The actual batch size is the largest batch size that is smaller than
+#'  `max_batch_size` and compatible with the requested `time_resolution`.
 #'  You should aim to set the batch size as large as possible given your
-#'  memory constrainty (boundary effects become larger the smaller the
+#'  memory constraints (boundary effects become larger the smaller the
 #'  batch size).
+#'
 #' @param time_resolution
-#'  The time resolution in physical units, generated by `u()`, or a pure number,
-#'  which is interpreted in unit of seconds.
+#'  The time resolution of the output signal in physical units (by [u()]),
+#'  or a pure number, which is interpreted in unit of seconds.
+#'  The time resolution of the high-resolution result will be reduced to
+#'  `time_resolution` by averaging fixed time slice windows.
 #'  Memory consumption is directly related to that.
-#'  Can not be smaller than the time resolution of the input signal.
+#'  `time_resolution` cannot be higher than the time resolution
+#'  of the input signal.
+#'
 #' @param 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 and printing the "loss ratio" and the number of batches.
+#'  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
@@ -59,35 +65,33 @@
 #'  The spectogram, a numeric real-valued matrix with dimensions roughly
 #'  `dim ~ c(length(signal) * time_resolution * 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
+#'  This matrix is wrapped into a S3-class "fcwtr_scalogram" so that plotting and
 #'  coercion functions can be used conveniently.
 #'
 #' @inheritParams fcwt
 #' @seealso [fcwt()]
-#' @importFrom utils txtProgressBar setTxtProgressBar
-#' @export
 #' @examples
-#' res <-
-#'   fcwt_batch(
-#'     ts_sin_sin,
-#'     sample_freq = 44100,
-#'     freq_begin = 100,
-#'     freq_end = 11000,
-#'     n_freqs = 30,
-#'     sigma = 10,
-#'     time_resolution = 0.01
-#'   )
+#' fcwt_batch(
+#'   ts_sin_sin,
+#'   sample_freq = 44100,
+#'   freq_begin = 100,
+#'   freq_end = 11000,
+#'   n_freqs = 30,
+#'   sigma = 10,
+#'   time_resolution = 0.01
+#' )
 #'
-#' res
+#' @importFrom utils txtProgressBar setTxtProgressBar
+#' @export
 fcwt_batch <- function(signal,
                        sample_freq,
                        n_freqs,
-                       time_resolution,
                        freq_begin = 2 * sample_freq / length(signal),
                        freq_end = sample_freq / 2,
                        freq_scale = c("linear", "log"),
                        sigma = 1,
                        # factor 2 as additional security measure
+                       time_resolution,
                        max_batch_size = ceiling(1 * 10^9 / (n_freqs * 8) / 2),
                        n_threads = 2L,
                        progress_bar = FALSE) {