Add fitted() and residuals() S3 methods for threedx models (#18)

.covrignore

@@ -1,3 +1,5 @@
 R/zzz.R
 R/threedx-package.R
 R/autoplot.R
+R/fitted.R
+R/residuals.R

NAMESPACE

@@ -3,7 +3,9 @@ if (getRversion() >= "3.6.0") {
   S3method(ggplot2::autoplot, threedx)
   S3method(ggplot2::autoplot, threedx_paths)
 }
+S3method(fitted,threedx)
 S3method(predict,threedx)
+S3method(residuals,threedx)
 export(draw_bootstrap)
 export(draw_bootstrap_weighted)
 export(draw_bootstrap_zero_mean)

R/fitted.R

@@ -0,0 +1,15 @@
+#' Extract fitted values from a `threedx` model
+#' 
+#' Returns the fitted one-step-ahead predictions for the training data of the
+#' `threedx` model. At least the first value will be missing.
+#' 
+#' @param object A `threedx` model as returned by [learn_weights()]
+#' @param ... Other arguments passed to `fitted()`, ignored
+#' 
+#' @return A numeric vector of same length as `object$y`
+#' 
+#' @export
+fitted.threedx <- function(object, ...) {
+  checkmate::assert_class(x = object, classes = "threedx")
+  return(object$fitted)
+}

R/learn_weights.R

@@ -1,20 +1,24 @@
-
 #' Fit a 3DX model to a time series
 #' 
+#' Returns a `threedx` model applied to time series `y` after learning the
+#' optimal set of parameters by minimizing a provided loss function. Use
+#' [predict.threedx()] to generate a forecast based on the fitted model.
+#' 
 #' @param y The time series to be forecasted as numeric vector (not as `ts()`
 #'   object)
-#' @param period_length The presumed length of `y`'s seasonal period
+#' @param period_length The presumed length of `y`'s seasonal period; for
+#'   example, `12L` for monthly observations, `7L` for daily observations, ...
 #' @param alphas_grid A data frame of possible parameter combinations to
 #'   generate the weights of the final model. The optimal parameter set will be
 #'   chosen based on the minimization of `loss_function`. The expected columns
 #'   are numeric and called `alpha`, `alpha_seasonal`, `alpha_seasonal_decay`.
 #'   At least one row must be provided. All values must be between 0 and 1.
-#'   This list can be generated via [list_sampled_alphas()] or
-#'   [list_edge_alphas()], for example, but you can generate it in any way you
-#'   like.
+#'   Use, for example, [list_sampled_alphas()] or
+#'   [list_edge_alphas()] to generate this data frame, or generate it in any way
+#'   you like.
 #' @param loss_function A function with first argument `y_hat` and optionally
 #'   more arguments. Usually, to compute a loss, at least an additional `y`
-#'   argument is required---to compute errors. Must be able to handle additional
+#'   argument is required to compute errors. Must be able to handle additional
 #'   parameters via `...` to allow for potential future changes in the set of
 #'   arguments passed to `loss_function` by [learn_weights()].
 #'   For examples, see [loss_mae()] or [loss_mae_with_observation_weight()].

R/loss_functions.R

@@ -1,4 +1,4 @@
-#' Observation-weighted mean-absolute error loss function
+#' Observation-weighted mean absolute error loss function
 #' 
 #' @param y_hat A numeric vector representing predictions
 #' @param y A numeric vector representing observations

R/predict.R

@@ -1,4 +1,3 @@
-
 #' Draw forecast sample paths from a fitted 3DX model
 #' 
 #' @details While `observation_driven` can be effective at forecasting wide
@@ -28,9 +27,9 @@
 #'   drawing from weighted historical observations directly instead of adding
 #'   innovation noise on the current mean forecast. This is similar to the
 #'   Non-Parametric Time Series forecaster (NPTS) described in
-#'   "GluonTS: Probabilistic Time Series Models in Python" (2019) by Flunkert et
-#'   al. (see https://arxiv.org/abs/1906.05264). If `FALSE`, sample paths will
-#'   be generated by adding innovation noise on top of the current weighted
+#'   "GluonTS: Probabilistic Time Series Models in Python" (2019) by Alexandrov
+#'   et al. (see <https://arxiv.org/abs/1906.05264>). If `FALSE`, sample paths
+#'   will be generated by adding innovation noise on top of the current weighted
 #'   average forecast.
 #' @param innovation_function A function with arguments `n` and `errors`. Must
 #'   be able to handle additional parameters via `...` to allow for potential

R/residuals.R

@@ -0,0 +1,15 @@
+#' Extract residuals from a `threedx` model
+#' 
+#' Returns the residuals from one-step-ahead predictions for the training data
+#' of the `threedx` model. At least the first value will be missing.
+#' 
+#' @param object A `threedx` model as returned by [learn_weights()]
+#' @param ... Other arguments passed to `residuals()`, ignored
+#' 
+#' @return A numeric vector of same length as `object$y`
+#' 
+#' @export
+residuals.threedx <- function(object, ...) {
+  checkmate::assert_class(x = object, classes = "threedx")
+  return(object$residuals)
+}

_pkgdown.yml

@@ -31,3 +31,5 @@ reference:
 - title: "Helper Functions"
   contents:
   - "k_largest_weights_sum_to_less_than_p_percent"
+  - "fitted.threedx"
+  - "residuals.threedx"