fcwt_batch: improve documentation, issue warning messages when loss r…

…atio is not okay, and print further info when progress_bar = TRUE.

R/fcwt_batch.R

@@ -37,6 +37,9 @@
 #'  conservative and taking into account that R might make copies when further
 #'  processing it.
 #'  The actual batch size depends on 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
+#'  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.
@@ -45,7 +48,12 @@
 #' @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. Defaults to `FALSE`.
+#'  bar to the console and 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`.
 #'
 #' @return
 #'  The spectogram, a numeric real-valued matrix with dimensions roughly
@@ -79,8 +87,8 @@ fcwt_batch <- function(signal,
                        freq_end = sample_freq / 2,
                        freq_scale = c("linear", "log"),
                        sigma = 1,
-                       # factor 4 as additional security measure
-                       max_batch_size = ceiling(1 * 10^9 / (n_freqs * 8) / 4),
+                       # factor 2 as additional security measure
+                       max_batch_size = ceiling(1 * 10^9 / (n_freqs * 8) / 2),
                        n_threads = 2L,
                        progress_bar = FALSE) {
   time_resolution <- as_sec(time_resolution)
@@ -117,17 +125,31 @@ fcwt_batch <- function(signal,
 
   signal_size <- w$size_n * floor(length(signal) / w$size_n) # cut off the rest
 
+  loss_ratio <- 2 * dt / batch_size
 
-  if (2 * dt >= batch_size) {
+  if (loss_ratio >= 1) {
     stop(paste0(
-      "Removing COI yields empty result. Typically that happens if ",
-      "the batch size is too small. ",
+      "The batch size is too small: low frequencies cannot be detected. ",
       "To avoid that you can either increase the batch size or raise the ",
-      "frequency range."
+      "minimum frequency.\n",
+      "Keeping the minimum frequency unchanged, you should have at least a batch size of: ",
+      ceiling(2 * dt / 0.1), "."
     ))
   }
 
+  if (loss_ratio >= 0.3) {
+    warning(paste0(
+      "The loss ratio is quite high: ", format(loss_ratio), "\n",
+      "Consider increasing the batch size to increase performance."
+    ))
+  }
+
+  btchs <- batches(batch_size, signal_size, dt)
+
   if (progress_bar) {
+    cat(paste0("Loss ratio: ", format(loss_ratio), "\n"))
+    cat(paste0("Number of batches: ", length(btchs), "\n"))
+
     pb <- txtProgressBar(min = 0, max = signal_size, style = 3)
 
     on.exit({
@@ -137,7 +159,7 @@ fcwt_batch <- function(signal,
   }
 
   lapply(
-    batches(batch_size, signal_size, dt),
+    btchs,
     function(batch) {
       begin <- batch[[1]]
       end <- batch[[2]]

tests/testthat/test-fcwt_batch.R

@@ -99,3 +99,36 @@ test_that("fcwt_batch progress bar does not err", {
     )
   )
 })
+
+test_that("fcwt_batch should err if batch size is too small.", {
+  expect_error(
+    fcwt_batch(
+      ts_sin_440,
+      sample_freq = 44100,
+      freq_begin = 50,
+      freq_end = 1000,
+      n_freqs = 10,
+      sigma = 1,
+      max_batch_size = 1000,
+      # no aggregation
+      time_resolution = 1 / 44100
+    )
+  )
+})
+
+test_that("fcwt_batch should warn if loss ratio is critical.", {
+  expect_warning(
+    fcwt_batch(
+      ts_sin_440,
+      sample_freq = 44100,
+      freq_begin = 50,
+      freq_end = 1000,
+      n_freqs = 10,
+      sigma = 1,
+      max_batch_size = 7000,
+      # no aggregation
+      time_resolution = 1 / 44100
+    )
+  )
+})
+