pkg/R/Forecaster.R

   1 #' Forecaster
   2 #'
   3 #' Forecaster (abstract class, implemented by all forecasters).
   4 #'
   5 #' A Forecaster object encapsulates parameters (which can be of various kinds, for
   6 #' example "Neighbors" method stores informations about the considered neighborhood for
   7 #' the current prediction task) and one main function: \code{predictSerie()}. This last
   8 #' function (by default) calls \code{predictShape()} to get a forecast of a centered
   9 #' serie, and then calls the "jump prediction" function -- see "field" section -- to
  10 #' adjust it based on the last observed values.
  11 #'
  12 #' @usage # Forecaster$new(pjump) #warning: predictShape() is unimplemented
  13 #'
  14 #' @field .params List of computed parameters (if applicable).
  15 #' @field .pjump Function: how to predict the jump at day interface? The arguments of
  16 #'   this function are -- in this order:
  17 #'   \itemize{
  18 #'     \item data : object output of \code{getData()},
  19 #'     \item today : index (integer or date) of the last known day in data,
  20 #'     \item memory : number of days to use in the past (including today),
  21 #'     \item horizon : number of time steps to predict,
  22 #'     \item params : optimized parameters in the main method \code{predictShape()},
  23 #'     \item ... : additional arguments.
  24 #'   }
  25 #'   .pjump returns an estimation of the jump after the last observed value.
  26 #'
  27 #' @section Methods:
  28 #' \describe{
  29 #' \item{\code{initialize(data, pjump)}}{
  30 #'   Initialize a Forecaster object with a Data object and a jump prediction function.}
  31 #' \item{\code{predictSerie(today,memory,horizon,...)}}{
  32 #'   Predict a new serie of \code{horizon} values at day index \code{today} using
  33 #'   \code{memory} days in the past.}
  34 #' \item{\code{predictShape(today,memory,horizon,...)}}{
  35 #'   Predict a new shape of \code{horizon} values at day index \code{today} using
  36 #'   \code{memory} days in the past.}
  37 #' \item{\code{getParameters()}}{
  38 #'   Return (internal) parameters.}
  39 #' }
  40 #'
  41 #' @docType class
  42 #' @format R6 class
  43 #'
  44 Forecaster = R6::R6Class("Forecaster",
  45     private = list(
  46         .params = list(),
  47         .pjump = NULL
  48     ),
  49     public = list(
  50         initialize = function(pjump)
  51         {
  52             private$.pjump <- pjump
  53             invisible(self)
  54         },
  55         predictSerie = function(data, today, memory, predict_from, horizon, ...)
  56         {
  57             # Parameters (potentially) computed during shape prediction stage
  58             predicted_shape = self$predictShape(data,today,memory,predict_from,horizon,...)
  59             predicted_delta = private$.pjump(data, today, memory, predict_from, horizon,
  60                 private$.params, ...)
  61
  62             # Predicted shape is aligned on the end of current day + jump
  63             c( data$getSerie(today)[if (predict_from>=2) 1:(predict_from-1) else c()],
  64                 predicted_shape - predicted_shape[1] + predicted_delta +
  65                     ifelse(predict_from>=2,
  66                         data$getSerie(today)[predict_from-1], tail(data$getSerie(today-1),1)) )
  67         },
  68         predictShape = function(data, today, memory, predict_from, horizon, ...)
  69             NULL #empty default implementation: to implement in inherited classes
  70         ,
  71         getParameters = function()
  72             private$.params
  73     )
  74 )