Skip to content
Snippets Groups Projects
Select Git revision
  • 6a13d75ebf1cad962ef45c80d31bbc27ed5b6ce2
  • master default protected
  • feature/quantileforecast
  • develop
  • add_kseq
5 results

rls_fit.R

Blame
  • Code owners
    Assign users and groups as approvers for specific file changes. Learn more.
    rls_fit.R 9.07 KiB
    # Do this in a separate file to see the generated help:
    #library(devtools)
    #document()
    #load_all(as.package("../../onlineforecast"))
    #?rls_fit
    
    #' This function fits the onlineforecast model to the data and returns either: model validation data or just the score value.
    #'
    #' 
    #' This function has three main purposes (in the examples these three are demonstrated in the examples):
    #' 
    #' - Returning model validation data, such as residuals and recursive estimated parameters.
    #' 
    #' - For optimizing the parameters using an R optimizer function. The parameters to optimize for is given in \code{prm}
    #'
    #' - Fitting a model to data and saving the final state in the model object (such that from that point the model can be updated recursively as new data is received).
    #' 
    #' Note, if the \code{scorefun} is given the \code{data$scoreperiod} must be set to (int or logical) define which points to be evaluated in the scorefun.
    #' 
    #' @title Fit an onlineforecast model with Recursive Least Squares (RLS).
    #' @param prm vector with the parameters for fitting. Deliberately as the first element to be able to use \code{\link{optim}} or other optimizer. If NA then the model will be fitted with the current values in the input expressions, see examples.
    #' @param model as an object of class forecastmodel: The model to be fitted.
    #' @param data as a data.list with the data to fit the model on.
    #' @param scorefun as a function (optional), default is \code{\link{rmse}}. If the score function is given it will be applied to the residuals of each horizon (only data$scoreperiod is included).
    #' @param returnanalysis as a logical. If FALSE then the sum of the scoreval on all horizons are returned, if TRUE a list with values for analysis.
    #' @param runcpp logical: If true the c++ implementation of RLS is run, if false the R implementation is run (slower).
    #' @param printout logical: If TRUE the offline parameters and the score function value are printed.
    #' @return Depends on:
    #' 
    #'     - If \code{returnanalysis} is TRUE a list containing:
    #' 
    #'         * \code{Yhat}: data.frame with forecasts for \code{model$kseq} horizons.
    #'
    #'         * \code{model}: The forecastmodel object cloned deep, so can be modified without changing the original object.
    #' 
    #'         * \code{data}: data.list with the data used, see examples on how to obtain the transformed data.
    #'
    #'         * \code{Lfitval}: list with RLS coefficients in a data.frame for each horizon, use \code{\link{plot_ts.rls_fit}} to plot them and to obtain them as a data.frame for each coefficient.
    #'
    #'         * \code{scoreval}: data.frame with the scorefun result on each horizon (only scoreperiod is included).
    #'
    #'     - If \code{returnanalysis} is FALSE (and \code{scorefun} is given): The sum of the score function on all horizons (specified with model$kseq).
    #'
    #' @seealso
    #' For optimizing parameters \code{\link{rls_optim}()}, for summary \code{summary.rls_fit}, for plotting \code{\link{plot_ts.rls_fit}()}, and the other functions starting with 'rls_'.
    #'
    #' @examples
    #'
    #'
    #' # Take data
    #' D <- subset(Dbuilding, c("2010-12-15", "2011-01-01"))
    #' D$y <- D$heatload
    #' # Define a simple model 
    #' model <- forecastmodel$new()
    #' model$output <- "y"
    #' model$add_inputs(Ta = "Ta",
    #' 		    mu = "one()")
    #' model$add_regprm("rls_prm(lambda=0.99)")
    #'
    #' # Before fitting the model, define which points to include in the evaluation of the score function
    #' D$scoreperiod <- in_range("2010-12-20", D$t)
    #' # And the sequence of horizons to fit for
    #' model$kseq <- 1:6
    #'
    #' # Now we can fit the model with RLS and get the model validation analysis data
    #' fit <- rls_fit(model = model, data = D)
    #' # What did we get back?
    #' names(fit)
    #' # The one-step forecast
    #' plot(D$y, type="l")