From baa5279ac013f9dd241b2a7a524a81909800b02c Mon Sep 17 00:00:00 2001 From: Roel Verbelen Date: Mon, 13 Jul 2020 15:32:29 +1000 Subject: [PATCH] allow additional arguments to be passed to stats::stl() --- DESCRIPTION | 2 +- R/time_decompose_methods.R | 10 ++++++---- man/anomalize.Rd | 16 +++++++++++----- man/anomalize_methods.Rd | 4 ++-- man/anomalize_package.Rd | 4 ---- man/decompose_methods.Rd | 28 +++++++++++++++++++++++----- man/plot_anomalies.Rd | 17 +++++++++++++---- man/plot_anomaly_decomposition.Rd | 14 +++++++++++--- man/tidyverse_cran_downloads.Rd | 6 ++++-- man/time_apply.Rd | 13 +++++++++++-- man/time_decompose.Rd | 13 ++++++++++--- man/time_frequency.Rd | 4 ++-- 12 files changed, 94 insertions(+), 37 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 4735691..b2cbdbc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -39,7 +39,7 @@ Imports: cli, crayon, rstudioapi -RoxygenNote: 6.1.1 +RoxygenNote: 7.1.0 Roxygen: list(markdown = TRUE) Suggests: tidyverse, diff --git a/R/time_decompose_methods.R b/R/time_decompose_methods.R index bdc8719..d10e8de 100644 --- a/R/time_decompose_methods.R +++ b/R/time_decompose_methods.R @@ -1,6 +1,8 @@ #' Methods that power time_decompose() #' #' @inheritParams time_decompose +#' @param robust logical indicating if robust fitting be used in the loess procedure of the underlying function call to [stats::stl()]. +#' @param ... Additional parameters passed to the underlying function call to [stats::stl()]. #' #' @return A `tbl_time` object containing the time series decomposition. #' @@ -25,7 +27,7 @@ #' @export #' @rdname decompose_methods -decompose_twitter <- function(data, target, frequency = "auto", trend = "auto", message = TRUE) { +decompose_twitter <- function(data, target, frequency = "auto", trend = "auto", message = TRUE, robust = TRUE, ...) { # Checks if (missing(target)) stop('Error in decompose_twitter(): argument "target" is missing, with no default', call. = FALSE) @@ -47,7 +49,7 @@ decompose_twitter <- function(data, target, frequency = "auto", trend = "auto", decomp_tbl <- data %>% dplyr::pull(!! target_expr) %>% stats::ts(frequency = freq) %>% - stats::stl(s.window = "periodic", robust = TRUE) %>% + stats::stl(s.window = "periodic", robust = robust, ...) %>% sweep::sw_tidy_decomp() %>% dplyr::select(-c(index, seasadj)) %>% # forecast::mstl() %>% @@ -141,7 +143,7 @@ decompose_twitter <- function(data, target, frequency = "auto", trend = "auto", #' @export #' @rdname decompose_methods -decompose_stl <- function(data, target, frequency = "auto", trend = "auto", message = TRUE) { +decompose_stl <- function(data, target, frequency = "auto", trend = "auto", message = TRUE, robust = TRUE, ...) { # Checks if (missing(target)) stop('Error in decompose_stl(): argument "target" is missing, with no default', call. = FALSE) @@ -162,7 +164,7 @@ decompose_stl <- function(data, target, frequency = "auto", trend = "auto", mess decomp_tbl <- data %>% dplyr::pull(!! target_expr) %>% stats::ts(frequency = freq) %>% - stats::stl(s.window = "periodic", t.window = trnd, robust = TRUE) %>% + stats::stl(s.window = "periodic", t.window = trnd, robust = robust, ...) %>% sweep::sw_tidy_decomp() %>% # forecast::mstl() %>% # as.tibble() %>% diff --git a/man/anomalize.Rd b/man/anomalize.Rd index 7498790..6634e8f 100644 --- a/man/anomalize.Rd +++ b/man/anomalize.Rd @@ -4,8 +4,14 @@ \alias{anomalize} \title{Detect anomalies using the tidyverse} \usage{ -anomalize(data, target, method = c("iqr", "gesd"), alpha = 0.05, - max_anoms = 0.2, verbose = FALSE) +anomalize( + data, + target, + method = c("iqr", "gesd"), + alpha = 0.05, + max_anoms = 0.2, + verbose = FALSE +) } \arguments{ \item{data}{A \code{tibble} or \code{tbl_time} object.} @@ -51,13 +57,13 @@ each with benefits. \strong{IQR}: -The IQR Method uses an innerquartile range of 25% and 75% to establish a baseline distribution around +The IQR Method uses an innerquartile range of 25\% and 75\% to establish a baseline distribution around the median. With the default \code{alpha = 0.05}, the limits are established by expanding the 25/75 baseline by an IQR Factor of 3 (3X). The IQR Factor = 0.15 / alpha (hense 3X with alpha = 0.05). To increase the IQR Factor controling the limits, decrease the alpha, which makes it more difficult to be an outlier. Increase alpha to make it easier to be an outlier. -The IQR method is used in \href{https://github.com/robjhyndman/forecast}{forecast::tsoutliers()}. +The IQR method is used in \href{https://github.com/robjhyndman/forecast}{\code{forecast::tsoutliers()}}. \strong{GESD}: @@ -68,7 +74,7 @@ drops below the critical value, all outliers are considered removed. Because thi involves continuous updating via a loop, it is slower than the IQR method. However, it tends to be the best performing method for outlier removal. -The GESD method is used in \href{https://github.com/twitter/AnomalyDetection}{AnomalyDection::AnomalyDetectionTs()}. +The GESD method is used in \href{https://github.com/twitter/AnomalyDetection}{\code{AnomalyDection::AnomalyDetectionTs()}}. } \examples{ diff --git a/man/anomalize_methods.Rd b/man/anomalize_methods.Rd index 75752ab..049f305 100644 --- a/man/anomalize_methods.Rd +++ b/man/anomalize_methods.Rd @@ -45,8 +45,8 @@ gesd(x, alpha = 0.05, max_anoms = 0.2, verbose = TRUE) } \references{ \itemize{ -\item The IQR method is used in \href{https://github.com/robjhyndman/forecast/blob/master/R/clean.R}{forecast::tsoutliers()} -\item The GESD method is used in Twitter's \href{https://github.com/twitter/AnomalyDetection}{AnomalyDetection} package and is also available as a function in \href{https://github.com/raunakms/GESD/blob/master/runGESD.R}{@raunakms's GESD method} +\item The IQR method is used in \href{https://github.com/robjhyndman/forecast/blob/master/R/clean.R}{\code{forecast::tsoutliers()}} +\item The GESD method is used in Twitter's \href{https://github.com/twitter/AnomalyDetection}{\code{AnomalyDetection}} package and is also available as a function in \href{https://github.com/raunakms/GESD/blob/master/runGESD.R}{@raunakms's GESD method} } } \seealso{ diff --git a/man/anomalize_package.Rd b/man/anomalize_package.Rd index cea18d3..44c93b9 100644 --- a/man/anomalize_package.Rd +++ b/man/anomalize_package.Rd @@ -3,11 +3,7 @@ \docType{package} \name{anomalize_package} \alias{anomalize_package} -\alias{anomalize_package-package} \title{anomalize: Tidy anomaly detection} -\description{ -anomalize: Tidy anomaly detection -} \details{ The 'anomalize' package enables a "tidy" workflow for detecting anomalies in data. The main functions are time_decompose(), anomalize(), and time_recompose(). diff --git a/man/decompose_methods.Rd b/man/decompose_methods.Rd index 7cc8e8e..8dce8da 100644 --- a/man/decompose_methods.Rd +++ b/man/decompose_methods.Rd @@ -6,11 +6,25 @@ \alias{decompose_stl} \title{Methods that power time_decompose()} \usage{ -decompose_twitter(data, target, frequency = "auto", trend = "auto", - message = TRUE) +decompose_twitter( + data, + target, + frequency = "auto", + trend = "auto", + message = TRUE, + robust = TRUE, + ... +) -decompose_stl(data, target, frequency = "auto", trend = "auto", - message = TRUE) +decompose_stl( + data, + target, + frequency = "auto", + trend = "auto", + message = TRUE, + robust = TRUE, + ... +) } \arguments{ \item{data}{A \code{tibble} or \code{tbl_time} object.} @@ -28,6 +42,10 @@ For twitter, the trend controls the period width of the median, which are used t \item{message}{A boolean. If \code{TRUE}, will output information related to \code{tbl_time} conversions, frequencies, and trend / median spans (if applicable).} + +\item{robust}{logical indicating if robust fitting be used in the loess procedure of the underlying function call to \code{\link[stats:stl]{stats::stl()}}.} + +\item{...}{Additional parameters passed to the underlying function call to \code{\link[stats:stl]{stats::stl()}}.} } \value{ A \code{tbl_time} object containing the time series decomposition. @@ -48,7 +66,7 @@ tidyverse_cran_downloads \%>\% } \references{ \itemize{ -\item The "twitter" method is used in Twitter's \href{https://github.com/twitter/AnomalyDetection}{AnomalyDetection package} +\item The "twitter" method is used in Twitter's \href{https://github.com/twitter/AnomalyDetection}{\code{AnomalyDetection} package} } } \seealso{ diff --git a/man/plot_anomalies.Rd b/man/plot_anomalies.Rd index 54aaa25..399cc40 100644 --- a/man/plot_anomalies.Rd +++ b/man/plot_anomalies.Rd @@ -4,10 +4,19 @@ \alias{plot_anomalies} \title{Visualize the anomalies in one or multiple time series} \usage{ -plot_anomalies(data, time_recomposed = FALSE, ncol = 1, - color_no = "#2c3e50", color_yes = "#e31a1c", - fill_ribbon = "grey70", alpha_dots = 1, alpha_circles = 1, - alpha_ribbon = 1, size_dots = 1.5, size_circles = 4) +plot_anomalies( + data, + time_recomposed = FALSE, + ncol = 1, + color_no = "#2c3e50", + color_yes = "#e31a1c", + fill_ribbon = "grey70", + alpha_dots = 1, + alpha_circles = 1, + alpha_ribbon = 1, + size_dots = 1.5, + size_circles = 4 +) } \arguments{ \item{data}{A \code{tibble} or \code{tbl_time} object.} diff --git a/man/plot_anomaly_decomposition.Rd b/man/plot_anomaly_decomposition.Rd index aa25801..bc3d82b 100644 --- a/man/plot_anomaly_decomposition.Rd +++ b/man/plot_anomaly_decomposition.Rd @@ -4,9 +4,17 @@ \alias{plot_anomaly_decomposition} \title{Visualize the time series decomposition with anomalies shown} \usage{ -plot_anomaly_decomposition(data, ncol = 1, color_no = "#2c3e50", - color_yes = "#e31a1c", alpha_dots = 1, alpha_circles = 1, - size_dots = 1.5, size_circles = 4, strip.position = "right") +plot_anomaly_decomposition( + data, + ncol = 1, + color_no = "#2c3e50", + color_yes = "#e31a1c", + alpha_dots = 1, + alpha_circles = 1, + size_dots = 1.5, + size_circles = 4, + strip.position = "right" +) } \arguments{ \item{data}{A \code{tibble} or \code{tbl_time} object.} diff --git a/man/tidyverse_cran_downloads.Rd b/man/tidyverse_cran_downloads.Rd index 46b33f5..bd3df19 100644 --- a/man/tidyverse_cran_downloads.Rd +++ b/man/tidyverse_cran_downloads.Rd @@ -4,12 +4,14 @@ \name{tidyverse_cran_downloads} \alias{tidyverse_cran_downloads} \title{Downloads of various "tidyverse" packages from CRAN} -\format{A \code{grouped_tbl_time} object with 6,375 rows and 3 variables: +\format{ +A \code{grouped_tbl_time} object with 6,375 rows and 3 variables: \describe{ \item{date}{Date of the daily observation} \item{count}{Number of downloads that day} \item{package}{The package corresponding to the daily download number} -}} +} +} \source{ The package downloads come from CRAN by way of the \code{cranlogs} package. } diff --git a/man/time_apply.Rd b/man/time_apply.Rd index 7e374e6..dbf5cc9 100644 --- a/man/time_apply.Rd +++ b/man/time_apply.Rd @@ -4,8 +4,17 @@ \alias{time_apply} \title{Apply a function to a time series by period} \usage{ -time_apply(data, target, period, .fun, ..., start_date = NULL, - side = "end", clean = FALSE, message = TRUE) +time_apply( + data, + target, + period, + .fun, + ..., + start_date = NULL, + side = "end", + clean = FALSE, + message = TRUE +) } \arguments{ \item{data}{A \code{tibble} with a date or datetime index.} diff --git a/man/time_decompose.Rd b/man/time_decompose.Rd index 093ddc8..a838e1b 100644 --- a/man/time_decompose.Rd +++ b/man/time_decompose.Rd @@ -4,9 +4,16 @@ \alias{time_decompose} \title{Decompose a time series in preparation for anomaly detection} \usage{ -time_decompose(data, target, method = c("stl", "twitter"), - frequency = "auto", trend = "auto", ..., merge = FALSE, - message = TRUE) +time_decompose( + data, + target, + method = c("stl", "twitter"), + frequency = "auto", + trend = "auto", + ..., + merge = FALSE, + message = TRUE +) } \arguments{ \item{data}{A \code{tibble} or \code{tbl_time} object.} diff --git a/man/time_frequency.Rd b/man/time_frequency.Rd index ce0a79c..d63d5a9 100644 --- a/man/time_frequency.Rd +++ b/man/time_frequency.Rd @@ -45,8 +45,8 @@ The \code{period} argument has three basic options for returning a frequency. Options include: \itemize{ \item \code{"auto"}: A target frequency is determined using a pre-defined template (see \code{template} below). -\item \code{time-based duration}: (e.g. "1 week" or "2 quarters" per cycle) -\item \code{numeric number of observations}: (e.g. 5 for 5 observations per cycle) +\item \verb{time-based duration}: (e.g. "1 week" or "2 quarters" per cycle) +\item \verb{numeric number of observations}: (e.g. 5 for 5 observations per cycle) } The \code{template} argument is only used when \code{period = "auto"}. The template is a tibble