From e169b5d568110a86282877de4fc44384dc6d6cb0 Mon Sep 17 00:00:00 2001
From: Benjamin Auder <benjamin.auder@somewhere>
Date: Thu, 6 Apr 2017 21:44:30 +0200
Subject: [PATCH] improve doc of computeForecast for realtime usage

---
 pkg/DESCRIPTION         | 24 +++++++++----------
 pkg/R/A_NAMESPACE.R     | 12 ++++++++++
 pkg/R/computeForecast.R | 53 +++++++++++++++++++++++++----------------
 3 files changed, 56 insertions(+), 33 deletions(-)

diff --git a/pkg/DESCRIPTION b/pkg/DESCRIPTION
index a897984..3aab84c 100644
--- a/pkg/DESCRIPTION
+++ b/pkg/DESCRIPTION
@@ -25,19 +25,19 @@ URL: http://git.auder.net/?p=talweg.git
 License: MIT + file LICENSE
 RoxygenNote: 5.0.1
 Collate:
-    'A_NAMESPACE.R'
-    'Data.R'
-    'Forecaster.R'
-    'F_Average.R'
-    'F_Neighbors.R'
-    'F_Persistence.R'
-    'F_Zero.R'
-    'Forecast.R'
-    'J_Neighbors.R'
-    'J_Persistence.R'
-    'J_Zero.R'
+    'plot.R'
     'computeError.R'
     'computeForecast.R'
+    'J_Zero.R'
+    'J_Persistence.R'
+    'J_Neighbors.R'
+    'F_Zero.R'
+    'F_Persistence.R'
+    'F_Neighbors.R'
+    'F_Average.R'
     'getData.R'
-    'plot.R'
     'utils.R'
+    'Forecaster.R'
+    'Forecast.R'
+    'Data.R'
+    'A_NAMESPACE.R'
diff --git a/pkg/R/A_NAMESPACE.R b/pkg/R/A_NAMESPACE.R
index bcd5df1..1d78d9c 100644
--- a/pkg/R/A_NAMESPACE.R
+++ b/pkg/R/A_NAMESPACE.R
@@ -1,6 +1,18 @@
 #' @include Data.R
 #' @include Forecast.R
 #' @include Forecaster.R
+#' @include utils.R
+#' @include getData.R
+#' @include F_Average.R
+#' @include F_Neighbors.R
+#' @include F_Persistence.R
+#' @include F_Zero.R
+#' @include J_Neighbors.R
+#' @include J_Persistence.R
+#' @include J_Zero.R
+#' @include computeForecast.R
+#' @include computeError.R
+#' @include plot.R
 #'
 #' @importFrom grDevices colors gray.colors
 #' @importFrom graphics abline hist par plot
diff --git a/pkg/R/computeForecast.R b/pkg/R/computeForecast.R
index 1e79118..35372b3 100644
--- a/pkg/R/computeForecast.R
+++ b/pkg/R/computeForecast.R
@@ -2,40 +2,51 @@
 #'
 #' Predict time-series curves for the selected days indices (lines in data).
 #'
-#' @param data Object of type \code{Data}, output of \code{getData()}
+#' @param data Object of type \code{Data}, output of \code{getData()}.
 #' @param indices Indices where to forecast (the day after); integers relative to the
-#'   beginning of data, or (convertible to) Date objects
-#' @param forecaster Name of the main forcaster
+#'   beginning of data, or (convertible to) Date objects.
+#' @param forecaster Name of the main forecaster; more details: ?F_<forecastername>
 #' \itemize{
-#'   \item Persistence : use values of last (similar, next) day
-#'   \item Neighbors : use values from the k closest neighbors' tomorrows
-#'   \item Average : global average of all the (similar) "tomorrow of past"
+#'   \item Persistence : use last (similar, next) day
+#'   \item Neighbors : weighted tomorrows of similar days
+#'   \item Average : average tomorrow of all same day-in-week
 #'   \item Zero : just output 0 (benchmarking purpose)
 #' }
-#' @param pjump How to predict the jump at the interface between two days ?
+#' @param pjump Function to predict the jump at the interface between two days;
+#'   more details: ?J_<functionname>
 #' \itemize{
-#'   \item Persistence : use last (similar) day values
-#'   \item Neighbors: re-use the weights optimized in corresponding forecaster
+#'   \item Persistence : use last (similar, next) day
+#'   \item Neighbors: re-use the weights from F_Neighbors
 #'   \item Zero: just output 0 (no adjustment)
 #' }
-#' @param memory Data depth (in days) to be used for prediction
-#' @param horizon Number of time steps to predict
-#' @param ncores Number of cores for parallel execution (1 to disable)
-#' @param ... Additional parameters for the forecasting models
+#' @param memory Data depth (in days) to be used for prediction.
+#' @param horizon Number of time steps to predict.
+#' @param ncores Number of cores for parallel execution (1 to disable).
+#' @param ... Additional parameters for the forecasting models.
 #'
 #' @return An object of class Forecast
 #'
 #' @examples
-#' ts_data = system.file("extdata","pm10_mesures_H_loc.csv",package="talweg")
-#' exo_data = system.file("extdata","meteo_extra_noNAs.csv",package="talweg")
-#' data = getData(ts_data, exo_data, input_tz="GMT", working_tz="GMT", predict_at=7)
-#' pred = computeForecast(data, 2200:2230, "Persistence", "Persistence", 500, 12)
+#' ts_data <- system.file("extdata","pm10_mesures_H_loc.csv",package="talweg")
+#' exo_data <- system.file("extdata","meteo_extra_noNAs.csv",package="talweg")
+#' data <- getData(ts_data, exo_data, input_tz="GMT", working_tz="GMT", predict_at=7)
+#' pred <- computeForecast(data, 2200:2230, "Persistence", "Zero",
+#'   memory=500, horizon=12, ncores=1)
 #' \dontrun{#Sketch for real-time mode:
-#' data = new("Data", ...)
-#' forecaster = new(..., data=data)
+#' data <- Data$new()
+#' # Initialize: first day has no predictions attached
+#' data$initialize()
+#' forecaster <- MyForecaster$new(myJumpPredictFunc)
 #' repeat {
-#'   data$append(some_new_data)
-#'   pred = forecaster$predict(data$getSize(), ...)
+#'   # During the night between days j and j+1:
+#'   data$appendExoHat(exogenous_predictions)
+#'   # In the morning 7am+ or afternoon 1pm+:
+#'   data$setMeasures(
+#'     data$getSize()-1,
+#'     times_from_H+1_yersteday_to_Hnow,
+#'     PM10_values_of_last_24h,
+#'     exogenous_measures_for_yersteday)
+#'   pred <- forecaster$predictSerie(data, data$getSize()-1, ...)
 #'   #do_something_with_pred
 #' }}
 #' @export
-- 
2.44.0