Update documentation

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## Version 6.0.0
 * Update Makevars for ARM version of Windows.
 * Sanitize internal usage of `do.call` to avoid huge backtraces.
-* Support lower triangular `distmat` objects for symmetric distances (#77).
+* Support lower triangular `distmat` objects for symmetric distances (#77) - breaking change.
 
 ## Version 5.5.12
 * Remove explicit C++ requirements.

R/DISTANCES-sdtw.R

@@ -21,6 +21,12 @@
 #'
 #' `r roxygen_proxy_symmetric()`
 #'
+#' Note that, due to the fact that this distance is not always zero when a series is compared
+#' against itself, this optimization is likely problematic for soft-DTW, as the `dist` object will
+#' be handled by many functions as if it had only zeroes in the diagonal. An exception is
+#' [tsclust()] when using partitional clustering with PAM centroids---actual diagonal values will
+#' be calculated and considered internally in that case.
+#'
 #' @references
 #'
 #' Cuturi, M., & Blondel, M. (2017). Soft-DTW: a Differentiable Loss Function for Time-Series. arXiv

R/RD-helpers.R

@@ -26,6 +26,9 @@ See the parallelization vignette for more information - `browseVignettes(\"dtwcl
 
 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`.
+Starting with version 6.0.0, this optimization means that the function returns an array with the lower triangular values of the distance matrix,
+similar to what [stats::dist()] does;
+see [DistmatLowerTriangular-class] for a helper to access elements as it if were a normal matrix.
 If you want to avoid this optimization, call [proxy::dist] by giving the same list of series in both `x` and `y`."
 }
 

inst/NEWS.Rd

@@ -11,6 +11,6 @@
 \itemize{
     \item Update Makevars for ARM version of Windows.
     \item Sanitize internal usage of \code{do.call} to avoid huge backtraces.
-    \item Support lower triangular \code{distmat} objects for symmetric distances. See PR #77 on GitHub.
+    \item Support lower triangular \code{distmat} objects for symmetric distances. This is a slightly breaking change, see PR #77 on GitHub.
 }
 }