'update'
[talweg.git] / pkg / R / Forecaster.R
... / ...
CommitLineData
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(pjump)}}{
32#' Initialize a Forecaster object with a jump prediction function.}
33#' \item{\code{predictSerie(data,today,memory,predict_from,horizon,...)}}{
34#' Predict the next curve (at index today) from predict_from to horizon (hours), using
35#' \code{memory} days in the past.}
36#' \item{\code{predictShape(data,today,memory,predict_from,horizon,...)}}{
37#' Predict the shape of the next curve (at index today) from predict_from to horizon
38#' (hours), using \code{memory} days in the past.}
39#' \item{\code{getParameters()}}{
40#' Return (internal) parameters.}
41#' }
42#'
43#' @docType class
44#' @format R6 class
45#'
46Forecaster = R6::R6Class("Forecaster",
47 private = list(
48 .params = list(),
49 .pjump = NULL
50 ),
51 public = list(
52 initialize = function(pjump)
53 {
54 private$.pjump <- pjump
55 invisible(self)
56 },
57 predictSerie = function(data, today, memory, predict_from, horizon, ...)
58 {
59 # Parameters (potentially) computed during shape prediction stage
60 predicted_shape <- self$predictShape(data,today,memory,predict_from,horizon,...)
61
62 if (is.na(predicted_shape[1]))
63 return (NA)
64
65 predicted_delta <- private$.pjump(data, today, memory, predict_from,
66 horizon, private$.params, first_pred=predicted_shape[1], ...)
67
68 # Predicted shape is aligned on the end of current day + jump
69 c( data$getSerie(today)[if (predict_from>=2) 1:(predict_from-1) else c()],
70 (predicted_shape - predicted_shape[1]) + #shape with first_pred = 0
71 ifelse(predict_from>=2, #last observed value
72 data$getSerie(today)[predict_from-1], tail(data$getSerie(today-1),1)) +
73 predicted_delta ) #jump
74 },
75 predictShape = function(data, today, memory, predict_from, horizon, ...)
76 NULL #empty default implementation: to implement in inherited classes
77 ,
78 getParameters = function()
79 private$.params
80 )
81)