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 if it's provided -- see "field"
  10 #' section -- to adjust it based on the last observed values. The main method in derived
  11 #' forecasters is \code{predictShape()}; see 'Methods' section.
  12 #'
  13 #' @usage # Forecaster$new(pjump) #warning: predictShape() is unimplemented
  14 #'
  15 #' @field .params List of computed parameters (if applicable).
  16 #' @field .pjump Function: how to predict the jump at day interface? The arguments of
  17 #'   this function are -- in this order:
  18 #'   \itemize{
  19 #'     \item data: object output of \code{getData()},
  20 #'     \item today: index of the current day in data (known until predict_from-1),
  21 #'     \item memory: number of days to use in the past (including today),
  22 #'     \item predict_from: first time step to predict (in [1,24])
  23 #'     \item horizon: last time step to predict (in [predict_from,24]),
  24 #'     \item params: optimized parameters in the main method \code{predictShape()},
  25 #'     \item ...: additional arguments.
  26 #'   }
  27 #'   .pjump returns an estimation of the jump after the last observed value.
  28 #'
  29 #' @section Methods:
  30 #' \describe{
  31 #' \item{\code{initialize(data, pjump)}}{
  32 #'   Initialize a Forecaster object with a Data object and a jump prediction function,
  33 #'   or NULL if \code{predictShape()} returns an adjusted curve.}
  34 #' \item{\code{predictSerie(data,today,memory,predict_from,horizon,...)}}{
  35 #'   Predict the next curve (at index today) from predict_from to horizon (hours), using
  36 #'   \code{memory} days in the past.}
  37 #' \item{\code{predictShape(data,today,memory,predict_from,horizon,...)}}{
  38 #'   Predict the shape of the next curve (at index today) from predict_from to horizon
  39 #'   (hours), using \code{memory} days in the past.}
  40 #' \item{\code{getParameters()}}{
  41 #'   Return (internal) parameters.}
  42 #' }
  43 #'
  44 #' @docType class
  45 #' @format R6 class
  46 #'
  47 Forecaster = R6::R6Class("Forecaster",
  48     private = list(
  49         .params = list(),
  50         .pjump = NULL
  51     ),
  52     public = list(
  53         initialize = function(pjump)
  54         {
  55             private$.pjump <- pjump
  56             invisible(self)
  57         },
  58         predictSerie = function(data, today, memory, predict_from, horizon, ...)
  59         {
  60             # Parameters (potentially) computed during shape prediction stage
  61             predicted_shape <- self$predictShape(data,today,memory,predict_from,horizon,...)
  62             predicted_delta <-
  63                 if (is.null(private$.pjump))
  64                     NULL
  65                 else
  66                     private$.pjump(data,today,memory,predict_from,horizon,private$.params,...)
  67
  68             # Predicted shape is aligned on the end of current day + jump (if jump!=NULL)
  69             c( data$getSerie(today)[if (predict_from>=2) 1:(predict_from-1) else c()],
  70                 predicted_shape + ifelse( is.null(private$.pjump),
  71                     0,
  72                     predicted_delta - predicted_shape[1] +
  73                         ifelse(predict_from>=2,
  74                             data$getSerie(today)[predict_from-1], tail(data$getSerie(today-1),1)) ) )
  75         },
  76         predictShape = function(data, today, memory, predict_from, horizon, ...)
  77             NULL #empty default implementation: to implement in inherited classes
  78         ,
  79         getParameters = function()
  80             private$.params
  81     )
  82 )