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 #' @field .params List of computed parameters (if applicable).
  13 #' @field .pjump Function: how to predict the jump at day interface? The arguments of
  14 #'   this function are -- in this order:
  15 #'   \itemize{
  16 #'     \item data : object output of \code{getData()},
  17 #'     \item today : index (integer or date) of the last known day in data,
  18 #'     \item memory : number of days to use in the past (including today),
  19 #'     \item horizon : number of time steps to predict,
  20 #'     \item params : optimized parameters in the main method \code{predictShape()},
  21 #'     \item ... : additional arguments.
  22 #'   }
  23 #'   .pjump returns an estimation of the jump after the last observed value.
  24 #'
  25 #' @section Methods:
  26 #' \describe{
  27 #' \item{\code{initialize(data, pjump)}}{
  28 #'   Initialize a Forecaster object with a Data object and a jump prediction function.}
  29 #' \item{\code{predictSerie(today,memory,horizon,...)}}{
  30 #'   Predict a new serie of \code{horizon} values at day index \code{today} using
  31 #'   \code{memory} days in the past.}
  32 #' \item{\code{predictShape(today,memory,horizon,...)}}{
  33 #'   Predict a new shape of \code{horizon} values at day index \code{today} using
  34 #'   \code{memory} days in the past.}
  35 #' \item{\code{getParameters()}}{
  36 #'   Return (internal) parameters.}
  37 #' }
  38 #'
  39 #' @docType class
  40 #' @format R6 class
  41 #'
  42 Forecaster = R6::R6Class("Forecaster",
  43     private = list(
  44         .params = list(),
  45         .pjump = NULL
  46     ),
  47     public = list(
  48         initialize = function(pjump)
  49         {
  50             private$.pjump <- pjump
  51             invisible(self)
  52         },
  53         predictSerie = function(data, today, memory, horizon, ...)
  54         {
  55             # Parameters (potentially) computed during shape prediction stage
  56             predicted_shape = self$predictShape(data, today, memory, horizon, ...)
  57             predicted_delta = private$.pjump(data,today,memory,horizon,private$.params,...)
  58             # Predicted shape is aligned it on the end of current day + jump
  59             predicted_shape+tail(data$getSerie(today),1)-predicted_shape[1]+predicted_delta
  60         },
  61         predictShape = function(data, today, memory, horizon, ...)
  62             NULL #empty default implementation: to implement in inherited classes
  63         ,
  64         getParameters = function()
  65             private$.params
  66     )
  67 )