Migrate away from man-roxygen templates

DESCRIPTION

@@ -83,6 +83,7 @@ Collate:
     'DISTANCES-sbd.R'
     'DISTANCES-sdtw.R'
     'GENERICS-cvi.R'
+    'RD-helpers.R'
     'S4-Distmat.R'
     'S4-DistmatLowerTriangular.R'
     'S4-PairTracker.R'

R/CENTROIDS-dba.R

@@ -21,7 +21,7 @@
 #' @param max.iter Maximum number of iterations allowed.
 #' @param delta At iteration `i`, if `all(abs(centroid_{i}` `-` `centroid_{i-1})` `< delta)`,
 #'   convergence is assumed.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #' @param trace If `TRUE`, the current iteration is printed to output.
 #' @param mv.ver Multivariate version to use. See below.
 #'
@@ -34,15 +34,13 @@
 #' the same result provided the elements of `X` keep the same values, although their order may
 #' change.
 #'
-#' @template rcpp-parallel
+#' `r roxygen_window_details()`
 #'
-#' @section Parallel Computing:
+#' @section `r roxygen_rcpp_parallel_section()`
 #'
 #'   This function appears to be very sensitive to numerical inaccuracies if multi-threading is used
 #'   in a **32 bit** installation. In such systems, consider limiting calculations to 1 thread.
 #'
-#' @template window
-#'
 #' @return The average time series.
 #'
 #' @section Multivariate series:

R/CENTROIDS-pam.R

@@ -13,7 +13,7 @@
 #' @param ids Integer vector indicating which of the `series` should be considered.
 #' @param distmat Optionally, a pre-computed cross-distance matrix of *all* `series`.
 #' @param ... Any extra parameters for the `distance` function that may be used.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'

R/CENTROIDS-sdtw-cent.R

@@ -41,7 +41,7 @@ sdtw_cent_stats_gr <- function(ignored, .shared_env_, ...) {
 #'   for `optim`, and `...` for both).
 #' @param opts List of options to pass to `nloptr` or [stats::optim()]'s `control`. The defaults in
 #'   the function's formals are for `nloptr`, but the value will be adjusted for `optim` if needed.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'
@@ -52,9 +52,7 @@ sdtw_cent_stats_gr <- function(ignored, .shared_env_, ...) {
 #' @return The resulting centroid, with the optimization results as attributes (except for the
 #'   returned centroid).
 #'
-#' @template rcpp-parallel
-#'
-#' @section Parallel Computing:
+#' @section `r roxygen_rcpp_parallel_section()`
 #'
 #'   For unknown reasons, this function has returned different results (in the order of 1e-6) when
 #'   using multi-threading in x64 Windows installations in comparison to other environments (using

R/CENTROIDS-shape-extraction.R

@@ -14,7 +14,7 @@
 #'   the matrices in `X`. **It will be z-normalized**.
 #' @param znorm Logical flag. Should z-scores be calculated for `X` before processing?
 #' @param ... Further arguments for [zscore()].
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'

R/CLUSTERING-tadpole.R

@@ -10,7 +10,7 @@
 #' @param window.size Window size constraint for DTW (Sakoe-Chiba). See details.
 #' @param k The number of desired clusters. Can be a vector with several values.
 #' @param dc The cutoff distance(s). Can be a vector with several values.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #' @param lb Which lower bound to use, "lbk" for [lb_keogh()] or "lbi" for [lb_improved()].
 #' @param trace Logical flag. If `TRUE`, more output regarding the progress is printed to screen.
 #'
@@ -39,7 +39,7 @@
 #' - For multiple `dc` values, multi-processing with [foreach::foreach()].
 #' - The internal distance calculations use multi-threading with [RcppParallel::RcppParallel].
 #'
-#' @template window
+#' `r roxygen_window_details()`
 #'
 #' @return
 #'
@@ -52,7 +52,7 @@
 #' For multiple `k`/`dc` values, a list of lists is returned, each internal list having the
 #' aforementioned elements.
 #'
-#' @template rcpp-parallel
+#' @section `r roxygen_rcpp_parallel_section()`
 #'
 #' @references
 #'

R/CLUSTERING-tsclust.R

@@ -106,7 +106,7 @@ pam_distmat <- function(series, control, distance, cent_char, family, args, trac
 #'   See [tsclust_args()] and the examples.
 #' @param seed Random seed for reproducibility.
 #' @param trace Logical flag. If `TRUE`, more output regarding the progress is printed to screen.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'
@@ -262,10 +262,15 @@ pam_distmat <- function(series, control, distance, cent_char, family, args, trac
 #'   Repetitions are greatly optimized when PAM centroids are used and the whole distance matrix is
 #'   precomputed, since said matrix is reused for every repetition.
 #'
-#' @template parallel
-#'
 #' @section Parallel Computing:
 #'
+#'   Please note that running tasks in parallel does **not** guarantee faster computations. The
+#'   overhead introduced is sometimes too large, and it's better to run tasks sequentially.
+#'
+#'   The user can register a parallel backend, e.g. with the \pkg{doParallel} package, in order to
+#'   attempt to speed up the calculations (see the examples). This relies on [foreach::foreach()],
+#'   i.e. it uses multi-processing.
+#'
 #'   Multi-processing is used in partitional and fuzzy clustering for multiple values of `k` and/or
 #'   `nrep` (in [partitional_control()]). See [TADPole()] to know how it uses parallelization. For
 #'   cross-distance matrix calculations, the parallelization strategy depends on whether the

R/DISTANCES-dtw-basic.R

@@ -19,23 +19,23 @@
 #' @param normalize Should the distance be normalized? Only supported for `symmetric2`.
 #' @param sqrt.dist Only relevant for `norm = "L2"`, see notes.
 #' @param ... Currently ignored.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'
 #' If `backtrack` is `TRUE`, the mapping of indices between series is returned in a list.
 #'
-#' @template window
+#' `r roxygen_window_details()`
 #'
 #' @return The DTW distance. For `backtrack` `=` `TRUE`, a list with:
 #'
 #'   - `distance`: The DTW distance.
 #'   - `index1`: `x` indices for the matched elements in the warping path.
 #'   - `index2`: `y` indices for the matched elements in the warping path.
 #'
-#' @template proxy
-#' @template symmetric
-#' @section Proxy version:
+#' @section `r roxygen_proxy_section()`
+#'
+#' `r roxygen_proxy_symmetric()`
 #'
 #'   In order for symmetry to apply here, the following must be true: no window constraint is used
 #'   (`window.size` is `NULL`) or, if one is used, all series have the same length.

R/DISTANCES-dtw-lb.R

@@ -9,7 +9,7 @@
 #' @param x,y A matrix or data frame where rows are time series, or a list of time series.
 #' @param window.size Window size to use with the LB and DTW calculation. See details.
 #' @param norm Either `"L1"` for Manhattan distance or `"L2"` for Euclidean.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #' @param pairwise Calculate pairwise distances?
 #' @param dtw.func Which function to use for the core DTW calculations, either "dtw" or "dtw_basic".
 #'   See [dtw::dtw()] and [dtw_basic()].
@@ -31,11 +31,11 @@
 #' This could be useful in case one is interested in only the nearest neighbor of one or more series
 #' within a dataset.
 #'
-#' @template window
+#' `r roxygen_window_details()`
 #'
 #' @return The distance matrix with class `crossdist`.
 #'
-#' @template rcpp-parallel
+#' @section `r roxygen_rcpp_parallel_section()`
 #'
 #' @note
 #'

R/DISTANCES-dtw2.R

@@ -26,7 +26,7 @@
 #' This wrapper simply returns the appropriate DTW distance using L2 norm (Euclidean norm). A
 #' [proxy::dist()] version is also registered.
 #'
-#' @template window
+#' `r roxygen_window_details()`
 #'
 #' @return An object of class `dtw`.
 #'

R/DISTANCES-gak.R

@@ -32,7 +32,7 @@ estimate_sigma <- function(x, y, within_proxy) {
 #'   `NULL`.
 #' @param window.size Parameterization of the constraining band (*T* in Cuturi (2011)). See details.
 #' @param normalize Normalize the result by considering diagonal terms.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'
@@ -55,8 +55,9 @@ estimate_sigma <- function(x, y, within_proxy) {
 #' The logarithm of the GAK if `normalize = FALSE`, otherwise 1 minus the normalized GAK. The value
 #' of `sigma` is assigned as an attribute of the result.
 #'
-#' @template proxy
-#' @template symmetric
+#' @section `r roxygen_proxy_section()`
+#'
+#' `r roxygen_proxy_symmetric()`
 #'
 #' @note
 #'

R/DISTANCES-lb-improved.R

@@ -16,7 +16,7 @@
 #' @param force.symmetry If `TRUE`, a second lower bound is calculated by swapping `x` and `y`, and
 #'   whichever result has a *higher* distance value is returned. The proxy version can only work if
 #'   a square matrix is obtained, but use carefully.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'
@@ -25,11 +25,11 @@
 #' If the envelopes are provided, they should be provided together. If either one is missing, both
 #' will be computed.
 #'
-#' @template window
+#' `r roxygen_window_details()`
 #'
 #' @return The improved lower bound for the DTW distance.
 #'
-#' @template proxy
+#' @section `r roxygen_proxy_section()`
 #'
 #' @section Note:
 #'

R/DISTANCES-lb-keogh.R

@@ -10,7 +10,7 @@
 #' @inherit lb_improved details
 #' @inheritSection lb_improved Note
 #'
-#' @template proxy
+#' @section `r roxygen_proxy_section()`
 #'
 #' @return A list with:
 #'

R/DISTANCES-sbd.R

@@ -7,7 +7,7 @@
 #'
 #' @param x,y Univariate time series.
 #' @param znorm Logical. Should each series be z-normalized before calculating the distance?
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #' @param return.shifted Logical. Should the shifted version of `y` be returned? See details.
 #'
 #' @details
@@ -26,9 +26,9 @@
 #' - `dist`: The shape-based distance between `x` and `y`.
 #' - `yshift`: A shifted version of `y` so that it optimally matches `x` (based on [NCCc()]).
 #'
-#' @template proxy
-#' @template symmetric
-#' @section Proxy version:
+#' @section `r roxygen_proxy_section()`
+#'
+#' `r roxygen_proxy_symmetric()`
 #'
 #'   In some situations, e.g. for relatively small distance matrices, the overhead introduced by the
 #'   logic that computes only half the distance matrix can be bigger than just calculating the whole

R/DISTANCES-sdtw.R

@@ -8,7 +8,7 @@
 #'   spanning the columns.
 #' @param gamma Positive regularization parameter, with lower values resulting in less smoothing.
 #' @param ... Currently ignored.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'
@@ -17,8 +17,9 @@
 #'
 #' @return The Soft DTW distance.
 #'
-#' @template proxy
-#' @template symmetric
+#' @section `r roxygen_proxy_section()`
+#'
+#' `r roxygen_proxy_symmetric()`
 #'
 #' @references
 #'

R/RD-helpers.R

@@ -0,0 +1,45 @@
+roxygen_error_check_param <- function() {
+    "Logical indicating whether the function should try to detect inconsistencies
+    and give more informative errors messages. Also used internally to avoid repeating checks."
+}
+
+roxygen_window_details <- function() {
+    "The windowing constraint uses a centered window.
+The calculations expect a value in `window.size` that represents the distance between the point considered and one of the edges of the window.
+Therefore, if, for example, `window.size = 10`, the warping for an observation \\eqn{x_i} considers the points between \\eqn{x_{i-10}} and \\eqn{x_{i+10}},
+resulting in `10(2) + 1 = 21` observations falling within the window."
+}
+
+roxygen_proxy_section <- function() {
+    "Proxy version:
+
+The version registered with [proxy::dist()] is custom (`loop = FALSE` in [proxy::pr_DB]).
+The custom function handles multi-threaded parallelization directly with [RcppParallel][RcppParallel::RcppParallel-package].
+It uses all available threads by default (see [RcppParallel::defaultNumThreads()]),
+but this can be changed by the user with [RcppParallel::setThreadOptions()].
+
+An exception to the above is when it is called within a [`foreach`][foreach::foreach] parallel loop **made by dtwclust**.
+If the parallel workers do not have the number of threads explicitly specified,
+this function will default to 1 thread per worker.
+See the parallelization vignette for more information - `browseVignettes(\"dtwclust\")`"
+}
+
+roxygen_proxy_symmetric <- function() {
+    "It also includes symmetric optimizations to calculate only half a distance matrix when appropriate---only one list of series should be provided in `x`.
+If you want to avoid this optimization, call [proxy::dist] by giving the same list of series in both `x` and `y`."
+}
+
+roxygen_rcpp_parallel_section <- function() {
+    "Parallel Computing:
+Please note that running tasks in parallel does **not** guarantee faster computations.
+The overhead introduced is sometimes too large, and it's better to run tasks sequentially.
+
+This function uses the [RcppParallel][RcppParallel::RcppParallel-package] package for parallelization.
+It uses all available threads by default (see [RcppParallel::defaultNumThreads()]),
+but this can be changed by the user with [RcppParallel::setThreadOptions()].
+
+An exception to the above is when it is called within a [`foreach`][foreach::foreach] parallel loop **made by dtwclust**.
+If the parallel workers do not have the number of threads explicitly specified,
+this function will default to 1 thread per worker.
+See the parallelization vignette for more information - `browseVignettes(\"dtwclust\")`"
+}

R/UTILS-compute-envelope.R

@@ -7,9 +7,11 @@
 #'
 #' @param x A univariate time series.
 #' @param window.size Window size for envelope calculation. See details.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
-#' @template window
+#' @details
+#'
+#' `r roxygen_window_details()`
 #'
 #' @return A list with two elements (lower and upper envelopes respectively): `lower` and `upper`.
 #'

R/UTILS-nccc.R

@@ -7,7 +7,7 @@
 #' @importFrom stats convolve
 #'
 #' @param x,y Univariate time series.
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @return The cross-correlation sequence with length `length(x) + length(y) - 1L`.
 #'

R/UTILS-zscore.R

@@ -12,7 +12,7 @@
 #'   list is provided in `x`.
 #' @param keep.attributes Should the mean and standard deviation returned by [base::scale()] be
 #'   preserved?
-#' @template error-check
+#' @param error.check `r roxygen_error_check_param()`
 #'
 #' @details
 #'