diff --git a/R/fcwt.R b/R/fcwt.R index c74e697..1f6aa68 100644 --- a/R/fcwt.R +++ b/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) #' diff --git a/R/fcwt_batch.R b/R/fcwt_batch.R index cee54ed..0ea1eb7 100644 --- a/R/fcwt_batch.R +++ b/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,8 +27,8 @@ #' 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 @@ -36,19 +36,25 @@ #' 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) { diff --git a/man/fcwt.Rd b/man/fcwt.Rd index c43b741..f9b4cbc 100644 --- a/man/fcwt.Rd +++ b/man/fcwt.Rd @@ -99,3 +99,6 @@ fcwt( sigma = 5 ) } +\seealso{ +\code{\link[=fcwt_batch]{fcwt_batch()}} +} diff --git a/man/fcwt_batch.Rd b/man/fcwt_batch.Rd index 91f2907..5e5fe41 100644 --- a/man/fcwt_batch.Rd +++ b/man/fcwt_batch.Rd @@ -8,11 +8,11 @@ fcwt_batch( 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, + time_resolution, max_batch_size = ceiling(1 * 10^9/(n_freqs * 8)/2), n_threads = 2L, progress_bar = FALSE @@ -32,11 +32,6 @@ are linearly or logarithmically distributed, depending on the \code{freq_scale} argument. Computation time increases when raising the number of frequency bins.} -\item{time_resolution}{The time resolution in physical units, generated by \code{u()}, or a pure number, -which is interpreted in unit of seconds. -Memory consumption is directly related to that. -Can not be smaller than the time resolution of the input signal.} - \item{freq_begin, freq_end}{Optionally specifies the frequency range \verb{[freq_end, freq_begin]}. If not specified the maximal meaningful frequency range, depending on the input signal, is taken. @@ -54,13 +49,22 @@ Defaults to 1. Larger (lower) value of sigma corresponds to a better (worse) frequency resolution and a worse (better) time resolution.} +\item{time_resolution}{The time resolution of the output signal in physical units (by \code{\link[=u]{u()}}), +or a pure number, which is interpreted in unit of seconds. +The time resolution of the high-resolution result will be reduced to +\code{time_resolution} by averaging fixed time slice windows. +Memory consumption is directly related to that. +\code{time_resolution} cannot be higher than the time resolution +of the input signal.} + \item{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 \code{time_resolution}. +The actual batch size is the largest batch size that is smaller than +\code{max_batch_size} and compatible with the requested \code{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).} \item{n_threads}{Number of threads used by the computation, if supported by your platform. @@ -70,7 +74,7 @@ only a single thread is used.} \item{progress_bar}{Monitoring progress can sometimes be useful when performing time consuming operations. Setting \code{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 @@ -81,13 +85,13 @@ Defaults to \code{FALSE}.} The spectogram, a numeric real-valued matrix with dimensions roughly \code{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 \code{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. } \description{ 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 @@ -112,23 +116,21 @@ high-frequency information would get lost.) 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 \code{fcwt()} boundary artefacts are automatically removed, -so some high frequency information at the beginning and the end of the +Attention: In contrast to \code{\link[=fcwt]{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 \code{min_freq}.) } \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 } \seealso{ \code{\link[=fcwt]{fcwt()}}