Fixes #417

NAMESPACE

@@ -13,6 +13,7 @@ export(arima_string)
 export(as_label)
 export(as_name)
 export(assign_value)
+export(auto_stationarize)
 export(calibrate_and_plot)
 export(chr_assign)
 export(ci_hi)

NEWS.md

@@ -6,6 +6,7 @@ None
 ## New Features
 1. Fix #459 - Add function `ts_growth_rate_vec()`
 2. Fix #463 - Add function `ts_adf_test()`
+3. Fix #417 - Add function `auto_stationarize()`
 
 ## Minor Fixes and Improvements
 1. Fix #456 Fix boilerplate examples to set the `.true` param to `FALSE`

R/util-auto-stationarize.R

@@ -0,0 +1,70 @@
+#' Automatically Stationarize Time Series Data
+#'
+#' @family Utility
+#'
+#' @author Steven P. Sanderson II, MPH
+#'
+#' @description This function attempts to make a non-stationary time series stationary.
+#' This function attempts to make a given time series stationary by applying transformations
+#' such as differencing or logarithmic transformation. If the time series is already
+#' stationary, it returns the original time series.
+#'
+#' @details
+#' If the input time series is non-stationary (determined by the Augmented Dickey-Fuller test),
+#' this function will try to make it stationary by applying a series of transformations:
+#' 1. It checks if the time series is already stationary using the Augmented Dickey-Fuller test.
+#' 2. If not stationary, it attempts a logarithmic transformation.
+#' 3. If the logarithmic transformation doesn't work, it applies differencing.
+#'
+#' @param .time_series A time series object to be made stationary.
+#'
+#' @examples
+#' # Example 1: Using the AirPassengers dataset
+#' auto_stationarize(AirPassengers)
+#'
+#' # Example 2: Using the BJsales dataset
+#' auto_stationarize(BJsales)
+#'
+#' @return
+#' If the time series is already stationary, it returns the original time series.
+#' If a transformation is applied to make it stationary, it returns a list with two elements:
+#' - stationary_ts: The stationary time series.
+#' - ndiffs: The order of differencing applied to make it stationary.
+#'
+#' @name auto_stationarize
+NULL
+
+#' @export
+#' @rdname auto_stationarize
+auto_stationarize <- function(.time_series) {
+    # Variables
+    time_series <- .time_series
+
+    # Check if the time series is already stationary
+    if (ts_adf_test(time_series)$p_value < 0.05) {
+        cat("The time series is already stationary via ts_adf_test().\n")
+        return(time_series)
+    } else {
+        cat("The time series is not stationary. Attempting to make it stationary...\n")
+    }
+
+    # Transformation (e.g., logarithmic)
+    if (ts_adf_test(log(time_series))$p_value < 0.05) {
+        cat("Logarithmic transformation made the time series stationary.")
+        return(log(time_series))
+    }
+
+    # Differencing
+    if (ts_adf_test(diff(time_series, 1))$p_value >= 0.05) {
+        diff_order <- forecast::ndiffs(time_series)
+        cat("Differencing of order", diff_order, "made the time series stationary.\n")
+    }
+
+    # Return
+    return(
+        list(
+            stationary_ts = diff(time_series, diff_order),
+            ndiffs = diff_order
+        )
+    )
+}