X-Git-Url: https://git.auder.net/?a=blobdiff_plain;f=pkg%2FR%2FForecaster.R;h=784f86e48d216ee270f3ae6e775d9297ad891a8e;hb=8ab6420267542d34b7428f978aa76ba939b9754b;hp=d5d5280c997a735f59215a09d464c3bdc2bf0eea;hpb=1e20780ee1505fac6c7ed68d340892c497524561;p=talweg.git

diff --git a/pkg/R/Forecaster.R b/pkg/R/Forecaster.R
index d5d5280..784f86e 100644
--- a/pkg/R/Forecaster.R
+++ b/pkg/R/Forecaster.R
@@ -1,50 +1,86 @@
-#' @title Forecaster (abstract class)
+#' Forecaster
 #'
-#' @description Abstract class to represent a forecaster (they all inherit this)
+#' Forecaster (abstract class, implemented by all forecasters).
 #'
-#' @field params List of computed parameters, for post-run analysis (dev)
-#' @field data Dataset, object of class Data
-#' @field pjump Function: how to predict the jump at day interface ?
-Forecaster = setRefClass(
-	Class = "Forecaster",
-
-	fields = list(
-		params = "list",
-		data = "Data",
-		pjump = "function"
+#' A Forecaster object encapsulates parameters (which can be of various kinds, for
+#' example "Neighbors" method stores informations about the considered neighborhood for
+#' the current prediction task) and one main function: \code{predictSerie()}. This last
+#' function (by default) calls \code{predictShape()} to get a forecast of a centered
+#' serie, and then calls the "jump prediction" function if it's provided -- see "field"
+#' section -- to adjust it based on the last observed values. The main method in derived
+#' forecasters is \code{predictShape()}; see 'Methods' section.
+#'
+#' @usage # Forecaster$new(pjump) #warning: predictShape() is unimplemented
+#'
+#' @field .params List of computed parameters (if applicable).
+#' @field .pjump Function: how to predict the jump at day interface? The arguments of
+#'   this function are -- in this order:
+#'   \itemize{
+#'     \item data: object output of \code{getData()},
+#'     \item today: index of the current day in data (known until predict_from-1),
+#'     \item memory: number of days to use in the past (including today),
+#'     \item predict_from: first time step to predict (in [1,24])
+#'     \item horizon: last time step to predict (in [predict_from,24]),
+#'     \item params: optimized parameters in the main method \code{predictShape()},
+#'     \item ...: additional arguments.
+#'   }
+#'   .pjump returns an estimation of the jump after the last observed value.
+#'
+#' @section Methods:
+#' \describe{
+#' \item{\code{initialize(data, pjump)}}{
+#'   Initialize a Forecaster object with a Data object and a jump prediction function,
+#'   or NULL if \code{predictShape()} returns an adjusted curve.}
+#' \item{\code{predictSerie(data,today,memory,predict_from,horizon,...)}}{
+#'   Predict the next curve (at index today) from predict_from to horizon (hours), using
+#'   \code{memory} days in the past.}
+#' \item{\code{predictShape(data,today,memory,predict_from,horizon,...)}}{
+#'   Predict the shape of the next curve (at index today) from predict_from to horizon
+#'   (hours), using \code{memory} days in the past.}
+#' \item{\code{getParameters()}}{
+#'   Return (internal) parameters.}
+#' }
+#'
+#' @docType class
+#' @format R6 class
+#'
+Forecaster = R6::R6Class("Forecaster",
+	private = list(
+		.params = list(),
+		.pjump = NULL
 	),
-
-	methods = list(
-		initialize = function(...)
+	public = list(
+		initialize = function(pjump)
 		{
-			"Initialize (generic) Forecaster object"
-
-			callSuper(...)
-			if (!hasArg(data))
-				stop("Forecaster must be initialized with a Data object")
-			params <<- list()
+			private$.pjump <- pjump
+			invisible(self)
 		},
-		predict = function(today, memory, horizon, ...)
+		predictSerie = function(data, today, memory, predict_from, horizon, ...)
 		{
-			"Obtain a new forecasted time-serie"
-
 			# Parameters (potentially) computed during shape prediction stage
-			predicted_shape = predictShape(today, memory, horizon, ...)
-			predicted_delta = pjump(data, today, memory, horizon, params, ...)
-			# Predicted shape is aligned it on the end of current day + jump
-			predicted_shape + tail(data$getSerie(today),1) - predicted_shape[1] + predicted_delta
-		},
-		predictShape = function(today, memory, horizon, ...)
-		{
-			"Shape prediction (centered curve)"
+			predicted_shape <- self$predictShape(data,today,memory,predict_from,horizon,...)
+
+			if (is.na(predicted_shape))
+				return (NA)
 
-			#empty default implementation: to implement in inherited classes
+			predicted_delta <-
+				if (is.null(private$.pjump))
+					NULL
+				else
+					private$.pjump(data,today,memory,predict_from,horizon,private$.params,...)
+
+			# Predicted shape is aligned on the end of current day + jump (if jump!=NULL)
+			c( data$getSerie(today)[if (predict_from>=2) 1:(predict_from-1) else c()],
+				predicted_shape + ifelse( is.null(private$.pjump),
+					0,
+					predicted_delta - predicted_shape[1] +
+						ifelse(predict_from>=2,
+							data$getSerie(today)[predict_from-1], tail(data$getSerie(today-1),1)) ) )
 		},
+		predictShape = function(data, today, memory, predict_from, horizon, ...)
+			NULL #empty default implementation: to implement in inherited classes
+		,
 		getParameters = function()
-		{
-			"Get parameters list"
-
-			params
-		}
+			private$.params
 	)
 )