Remove graphics from {fabletools} - now available in {ggtime}

Author: mitchelloharawild

DESCRIPTION

@@ -67,7 +67,8 @@ Suggests:
     lubridate,
     urca,
     mvtnorm,
-    Matrix
+    Matrix,
+    ggtime
 VignetteBuilder: 
     knitr
 RdMacros: 

NAMESPACE

@@ -33,11 +33,6 @@ S3method(as_tsibble,fbl_ts)
 S3method(as_tsibble,grouped_fbl)
 S3method(augment,mdl_df)
 S3method(augment,mdl_ts)
-S3method(autolayer,fbl_ts)
-S3method(autolayer,tbl_ts)
-S3method(autoplot,dcmp_ts)
-S3method(autoplot,fbl_ts)
-S3method(autoplot,tbl_ts)
 S3method(coef,mdl_df)
 S3method(coef,mdl_ts)
 S3method(common_periods,default)
@@ -85,7 +80,6 @@ S3method(forecast,null_mdl)
 S3method(format,agg_vec)
 S3method(format,lst_mdl)
 S3method(format,mdl_ts)
-S3method(fortify,fbl_ts)
 S3method(gather,mdl_df)
 S3method(generate,"NULL")
 S3method(generate,lst_mdl)

NEWS.md

@@ -1,5 +1,9 @@
 # fabletools (development version)
 
+This release migrates graphics functionality to `{ggtime}`. The commonly used graphics functions are currently exported with a soft deprecation message. To use the `autoplot()` and `autolayer()` time series plot helper functions please include `library(ggtime)` in your code.
+
+After a (very) gradual deprecation process, the `{ggtime}` dependency will be removed and the graphics functions will stop being re-exported. This deprecation process is planned to span approximately 2 years, after which explicitly using `{ggtime}` will be required.
+
 # fabletools 0.5.1
 
 Compatibility release for upcoming ggplot2 4.0.0 release.

R/components.R

@@ -6,6 +6,9 @@
 #' A dable will be returned, which will allow you to easily plot the components
 #' and see the way in which components are combined to give forecasts.
 #' 
+#' The components can also be visualised using the [`autoplot()`] method provided
+#' by the ggtime package.
+#' 
 #' @param object A mable.
 #' @param ... Other arguments passed to methods.
 #' 
@@ -16,9 +19,8 @@
 #' # Forecasting with an ETS(M,Ad,A) model to Australian beer production
 #' aus_production %>%
 #'   model(ets = ETS(log(Beer) ~ error("M") + trend("Ad") + season("A"))) %>% 
-#'   components() %>% 
-#'   autoplot()
-#'
+#'   components()
+#' 
 #' @rdname components
 #' @export
 components.mdl_df <- function(object, ...){

R/dable.R

@@ -4,8 +4,8 @@
 #' data structure for representing decompositions. This data class is useful for
 #' representing decompositions, as its print method describes how its columns
 #' can be combined to produce the original data, and has a more appropriate
-#' `autoplot()` method for displaying decompositions. Beyond this, a dable
-#' (`dcmp_ts`) behaves very similarly to a tsibble (`tbl_ts`).
+#' `autoplot()` method for displaying decompositions provided by ggtime.
+#' Beyond this, a dable (`dcmp_ts`) behaves very similarly to a tsibble (`tbl_ts`).
 #'
 #' @param ... Arguments passed to [tsibble::tsibble()].
 #' @param response The name of the response variable column.

R/model_decomposition.R

@@ -101,6 +101,7 @@ Please check that you have specified the decomposition models appropriately.")
 #' library(feasts)
 #' library(tsibble)
 #' library(dplyr)
+#' library(ggtime)
 #' 
 #' vic_food <- tsibbledata::aus_retail %>% 
 #'   filter(State == "Victoria", Industry == "Food retailing")

R/plot.R

@@ -17,8 +17,13 @@
 #'  autoplot(vars(Close, log(Close)))
 #' 
 #' @importFrom ggplot2 ggplot aes geom_line guides guide_legend xlab
-#' @export
 autoplot.tbl_ts <- function(object, .vars = NULL, ...){
+  lifecycle::deprecate_soft(
+    when = "0.6.0",
+    what = "autoplot.tbl_ts()",
+    with = "ggtime::autoplot.tbl_ts()",
+    details = "Graphics functions have been moved to the {ggtime} package. Please use `library(ggtime)` instead."
+  )
   quo_vars <- enquo(.vars)
 
   kv <- key_vars(object)
@@ -76,8 +81,13 @@ autoplot.tbl_ts <- function(object, .vars = NULL, ...){
 
 #' @rdname autoplot.tbl_ts
 #' @importFrom ggplot2 ggplot aes geom_line guides guide_legend xlab
-#' @export
 autolayer.tbl_ts <- function(object, .vars = NULL, ...){
+  lifecycle::deprecate_soft(
+    when = "0.6.0",
+    what = "autolayer.tbl_ts()",
+    with = "ggtime::autolayer.tbl_ts()",
+    details = "Graphics functions have been moved to the {ggtime} package. Please use `library(ggtime)` instead."
+  )
   quo_vars <- enquo(.vars)
   kv <- key_vars(object)
   nk <- n_keys(object)
@@ -121,7 +131,6 @@ autolayer.tbl_ts <- function(object, .vars = NULL, ...){
 }
 
 #' @importFrom ggplot2 fortify
-#' @export
 fortify.fbl_ts <- function(model, data = NULL, level = c(80, 95), ...){
   return(as_tibble(model))
 }
@@ -152,8 +161,14 @@ fortify.fbl_ts <- function(model, data = NULL, level = c(80, 95), ...){
 #'   autoplot(aus_production)
 #' 
 #' @importFrom ggplot2 facet_wrap
-#' @export
 autoplot.fbl_ts <- function(object, data = NULL, level = c(80, 95), show_gap = TRUE, ...){
+  lifecycle::deprecate_soft(
+    when = "0.6.0",
+    what = "autoplot.fbl_ts()",
+    with = "ggtime::autoplot.fbl_ts()",
+    details = "Graphics functions have been moved to the {ggtime} package. Please use `library(ggtime)` instead."
+  )
+
   fc_resp <- response_vars(object)
   fc_key <- setdiff(key_vars(object), ".model")
   common_models <- duplicated(key_data(object)[[".model"]] %||% rep(TRUE, NROW(key_data(object))))
@@ -219,10 +234,14 @@ autoplot.fbl_ts <- function(object, data = NULL, level = c(80, 95), show_gap = T
 #' aus_production %>% 
 #'   autoplot(Beer) + 
 #'   autolayer(fc)
-#' 
-#' @export
 autolayer.fbl_ts <- function(object, data = NULL, level = c(80, 95), 
                              point_forecast = list(mean = mean), show_gap = TRUE, ...){
+  lifecycle::deprecate_soft(
+    when = "0.6.0",
+    what = "autolayer.fbl_ts()",
+    with = "ggtime::autolayer.fbl_ts()",
+    details = "Graphics functions have been moved to the {ggtime} package. Please use `library(ggtime)` instead."
+  )
   build_fbl_layer(object = object, data = data, level = level, 
                   point_forecast = point_forecast, show_gap = show_gap, ...)
 
@@ -470,9 +489,14 @@ build_fbl_layer <- function(object, data = NULL, level = c(80, 95),
 #'   autoplot()
 #' 
 #' @importFrom ggplot2 ggplot geom_line geom_rect facet_grid vars ylab labs after_stat
-#' @export
 autoplot.dcmp_ts <- function(object, .vars = NULL, scale_bars = TRUE, 
                              level = c(80, 95), ...){
+  lifecycle::deprecate_soft(
+    when = "0.6.0",
+    what = "autoplot.dcmp_ts()",
+    with = "ggtime::autoplot.dcmp_ts()",
+    details = "Graphics functions have been moved to the {ggtime} package. Please use `library(ggtime)` instead."
+  )
   method <- object%@%"method"
   idx <- index(object)
   keys <- key(object)

R/zzz.R

@@ -45,4 +45,31 @@ register_s3_method <- function(pkg, generic, class, fun = NULL) {
     }
   )
 }
+
+.onAttach <- function(...) {
+  ggtime_version <- package_version(as.character(packageDescription("ggtime", fields = "Version")))
+  if (!is.na(ggtime_version)) {
+    ggtime_ns <- getNamespace("ggtime")
+    
+    register_s3_method("ggplot2", "autoplot", "tbl_ts", getS3method("autoplot", "tbl_ts", envir = ggtime_ns))
+    register_s3_method("ggplot2", "autolayer", "tbl_ts", getS3method("autolayer", "tbl_ts", envir = ggtime_ns))
+    register_s3_method("ggplot2", "autoplot", "dcmp_ts", getS3method("autoplot", "dcmp_ts", envir = ggtime_ns))
+    if (ggtime_version >= "0.2.0") {
+      register_s3_method("ggplot2", "autoplot", "fbl_ts", getS3method("autoplot", "fbl_ts", envir = ggtime_ns))
+      register_s3_method("ggplot2", "autolayer", "fbl_ts", getS3method("autolayer", "fbl_ts", envir = ggtime_ns))
+      register_s3_method("ggplot2", "fortify", "tbl_ts", getS3method("fortify", "fbl_ts", envir = ggtime_ns))
+    } else {
+      register_s3_method("ggplot2", "autoplot", "fbl_ts", autoplot.fbl_ts)
+      register_s3_method("ggplot2", "autolayer", "fbl_ts", autolayer.fbl_ts)
+      register_s3_method("ggplot2", "fortify", "tbl_ts", fortify.fbl_ts)
+    }
+  } else {
+    register_s3_method("ggplot2", "autoplot", "fbl_ts", autoplot.fbl_ts)
+    register_s3_method("ggplot2", "autoplot", "tbl_ts", autoplot.tbl_ts)
+    register_s3_method("ggplot2", "autoplot", "dcmp_ts", autoplot.dcmp_ts)
+    register_s3_method("ggplot2", "autolayer", "fbl_ts", autolayer.fbl_ts)
+    register_s3_method("ggplot2", "autolayer", "tbl_ts", autolayer.fbl_ts)
+    register_s3_method("ggplot2", "fortify", "tbl_ts", fortify.fbl_ts)
+  }
+}
 # nocov end

_pkgdown.yml

@@ -130,13 +130,10 @@ reference:
     - new_transformation
 - title: Graphics
   desc: >
-    Some `autoplot()` and `autolayer()` methods are defined for classes commonly used within fabletools.
-  contents:
-    - autoplot.tbl_ts
-    - autolayer.tbl_ts
-    - autoplot.fbl_ts
-    - autolayer.fbl_ts
-    - autoplot.dcmp_ts
+    Graphics capabilities in feasts have moved to the [ggtime](https://pkg.mitchelloharawild.com/ggtime) package.
+
+    Please use `library(ggtime)` in your code in order to continue using the `autoplot()` and `autolayer()` functions previously provided by this package.
+
 - title: Extension package helpers
   desc: >
     Functions provided to help develop extension packages.