143 check for plane shape documentation issues

R/planes.R

@@ -426,7 +426,10 @@ plane_repeat <- function(location, input, seed, tolerance = NULL, prepend = NULL
 #' plane_score(input = prepped_forecast, seed = prepped_seed, components = c("cover","taper"))
 #'
 #' ## run plane scoring with all components and additional args
-#' comp_args <- list("trend" = list("sig_lvl" = 0.05), "repeat" = list("prepend" = 4, "tolerance" = 8))
+#' trend_args <- list("sig_lvl" = 0.05)
+#' repeat_args <- list("prepend" = 4, "tolerance" = 8)
+#' shape_args <- list("method" = "dtw")
+#' comp_args <- list("trend" = trend_args, "repeat" = repeat_args, "shape" = shape_args)
 #' plane_score(input = prepped_forecast, seed = prepped_seed, args = comp_args)
 #'
 #' ## run plane scoring with specific components and weights
@@ -748,7 +751,7 @@ plane_trend <- function(location, input, seed, sig_lvl = 0.1) {
 #'
 #' @details
 #'
-#' The approach for determining shapes can be customized by the user with the `plane_shape()` "method" argument. The two methods available are "sdiff" (default) and "dtw".
+#' The approach for determining shapes can be customized by the user with the `plane_shape()` "method" argument. The two methods available are "sdiff" (default) and "dtw". Compared with "sdiff", the "dtw" method has been shown to have a higher sensitivity, lower specificity, and much greater computational cost in some circumstances. The "sdiff" method is recommended if computational efficiency is a concern.
 #'
 #' The "sdiff" method will use consecutive scaled differences to construct shapes. The algorithm operates in three steps:
 #'
@@ -802,8 +805,10 @@ plane_trend <- function(location, input, seed, sig_lvl = 0.1) {
 #' prepped_seed <- plane_seed(prepped_observed, cut_date = "2022-10-29")
 #'
 #' ## run plane component
-#' plane_shape(location = "13", input = prepped_forecast, seed = prepped_seed)
+#' plane_shape(location = "37", input = prepped_forecast, seed = prepped_seed)
 #'
+#' ## run plane component with DTW method
+#' plane_shape(location = "37", input = prepped_forecast, seed = prepped_seed, method = "dtw")
 #'
 plane_shape <- function(location, input, seed, method = "sdiff") {
 

inst/app/app.R

@@ -60,7 +60,7 @@ ui <- navbarPage(title = "rplanes Explorer",
                                                                                                numericInput("tol", label = "Tolerance (Repeat)", value = 0, min = 0, max = 50, step = 1),
                                                                                                numericInput("pre", label = "Prepend Values (Repeat)",  value = 0, min = 0, max = 365, step = 1))),
                                                                            shinyjs::hidden(div(id = "args_shape",
-                                                                                               radioButtons("method", label = "Method (Shape)", choices = c("Default" = "sdiff", "Dynamic Time Warping" = "dtw"), selected = "sdiff")))
+                                                                                               radioButtons("method", label = "Method (Shape)", choices = c("sdiff (Default)" = "sdiff", "Dynamic Time Warping" = "dtw"), selected = "sdiff")))
                                                        )),
                                                        actionBttn("run", "Analyze", style = "unite", color = "danger"),
                                                        actionBttn("reset", "Reset", style = "stretch", color = "warning")

vignettes/planes-components.Rmd

@@ -38,7 +38,7 @@ tibble(
   `Function` = c("plane_diff()","plane_cover()","plane_taper()","plane_repeat()","plane_trend()", "plane_shape()", "plane_zero()"),
   `Forecast` = c("YES","YES","YES","YES","YES", "YES", "YES"),
   `Observed` = c("YES","NO","NO","YES","NO", "NO", "YES"),
-  `Parameters` = c("None","None","None","Tolerated number of repeats; Number of observations to prepend","Significance level for trend change", "None", "None")
+  `Parameters` = c("None","None","None","Tolerated number of repeats; Number of observations to prepend","Significance level for trend change", "Method used to identify unique shapes (sdiff or dtw)", "None")
 ) %>%
   knitr::kable()
 ```
@@ -801,6 +801,8 @@ ggplot(data = trend_dat, mapping = aes(x = date, y = flu.admits)) +
 
 The shape component evaluates the shape of the trajectory of the forecast signal and compares that shape to existing shapes in the observed seed data. If the shape is identified as novel, a flag is raised, and the signal is considered implausible. 
 
+This component has one additional argument that defines the method used to identify shapes - one of "sdiff" (default) or "dtw." Based on preliminary analyses, the DTW method has a higher sensitivity and a slightly lower specificity than the "sdiff" method but is much more computationally expensive.
+
 For more information on the shape algorithm, see `?plane_shape()`.
 
 ### Flagged as implausible
@@ -919,8 +921,6 @@ shape_dat %>%
 ```
 
 
-
-
 ## Zero - `plane_zero()`
 
 This function checks for the presence of any value(s) equal to zero in the evaluated signal. If there are any zeros found, then the function will look in the seed to see if there are zeros anywhere else in the time series. If so, the function will consider the evaluated zero plausible and no flags will be raised (i.e., indicator returned as `FALSE`). If not, the function will consider the evaluated zero implausible and a flag will be raised (i.e., indicator returned as `TRUE`). This function can be used on either forecast or observed signals.