prepare package for yearly report
[talweg.git] / pkg / R / Forecaster.R
CommitLineData
25b75559 1#' Forecaster
e030a6e3 2#'
102bcfda 3#' Forecaster (abstract class, implemented by all forecasters).
e030a6e3 4#'
102bcfda
BA
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
4f3fdbb8
BA
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.
a66a84b5 12#'
4e821712 13#' @usage # Forecaster$new(pjump) #warning: predictShape() is unimplemented
689aa1d3 14#'
102bcfda
BA
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{
4f3fdbb8
BA
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.
102bcfda
BA
26#' }
27#' .pjump returns an estimation of the jump after the last observed value.
25b75559 28#'
98e958ca
BA
29#' @section Methods:
30#' \describe{
31#' \item{\code{initialize(data, pjump)}}{
4f3fdbb8
BA
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
102bcfda 36#' \code{memory} days in the past.}
4f3fdbb8
BA
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.}
98e958ca 40#' \item{\code{getParameters()}}{
546b0cb6
BA
41#' Return (internal) parameters.}
42#' }
43#'
102bcfda
BA
44#' @docType class
45#' @format R6 class
46#'
25b75559
BA
47Forecaster = R6::R6Class("Forecaster",
48 private = list(
a66a84b5 49 .params = list(),
a66a84b5 50 .pjump = NULL
e030a6e3 51 ),
25b75559 52 public = list(
98e958ca 53 initialize = function(pjump)
a66a84b5 54 {
a66a84b5
BA
55 private$.pjump <- pjump
56 invisible(self)
57 },
d2ab47a7 58 predictSerie = function(data, today, memory, predict_from, horizon, ...)
a66a84b5
BA
59 {
60 # Parameters (potentially) computed during shape prediction stage
4f3fdbb8
BA
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,...)
d2ab47a7 67
4f3fdbb8 68 # Predicted shape is aligned on the end of current day + jump (if jump!=NULL)
d2ab47a7 69 c( data$getSerie(today)[if (predict_from>=2) 1:(predict_from-1) else c()],
4f3fdbb8
BA
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)) ) )
a66a84b5 75 },
d2ab47a7 76 predictShape = function(data, today, memory, predict_from, horizon, ...)
5d83d815 77 NULL #empty default implementation: to implement in inherited classes
25b75559 78 ,
e030a6e3 79 getParameters = function()
a66a84b5 80 private$.params
e030a6e3
BA
81 )
82)