added a SSMbespoke component

Author: Jouni Helske

ChangeLog

@@ -1,3 +1,8 @@
+Changes from version 1.5.1 to 1.6.0
+   * Added a new function `SSMbespoke` to be used inside `SSModel`. This allows
+     users to abstract the functionality of `SSMcustom` via their own bespoke 
+     function using, e.g., `SSMbespoke(myfun()) in the model formula.
+
 Changes from version 1.5.0 to 1.5.1
    * Added explicit alias for KFAS-package due to changes in roxygen2.
 

DESCRIPTION

@@ -1,32 +1,32 @@
-Package: KFAS
-Version: 1.5.1
-Title: Kalman Filter and Smoother for Exponential Family State Space Models
-Authors@R: 
-    person(given = "Jouni",
-           family = "Helske",
-           role = c("aut", "cre"),
-           email = "jouni.helske@iki.fi",
-           comment = c(ORCID = "0000-0001-7130-793X"))
-Depends:
-    R (>= 3.1.0)
-Imports:
-    stats
-Suggests:
-    knitr,
-    lme4,
-    MASS,
-    Matrix,
-    testthat
-Description: State space modelling is an efficient and flexible framework for 
-    statistical inference of a broad class of time series and other data. KFAS 
-    includes computationally efficient functions for Kalman filtering, smoothing, 
-    forecasting, and simulation of multivariate exponential family state space models, 
-    with observations from Gaussian, Poisson, binomial, negative binomial, and gamma 
-    distributions. See the paper by Helske (2017) <doi:10.18637/jss.v078.i10> for details.
-License: GPL (>= 2)
-BugReports: https://github.com/helske/KFAS/issues
-VignetteBuilder: knitr
-RoxygenNote: 7.2.3
-Encoding: UTF-8
-ByteCompile: true
-URL: https://github.com/helske/KFAS
+Package: KFAS
+Version: 1.6.0
+Title: Kalman Filter and Smoother for Exponential Family State Space Models
+Authors@R: 
+    person(given = "Jouni",
+           family = "Helske",
+           role = c("aut", "cre"),
+           email = "jouni.helske@iki.fi",
+           comment = c(ORCID = "0000-0001-7130-793X"))
+Depends:
+    R (>= 3.1.0)
+Imports:
+    stats
+Suggests:
+    knitr,
+    lme4,
+    MASS,
+    Matrix,
+    testthat
+Description: State space modelling is an efficient and flexible framework for 
+    statistical inference of a broad class of time series and other data. KFAS 
+    includes computationally efficient functions for Kalman filtering, smoothing, 
+    forecasting, and simulation of multivariate exponential family state space models, 
+    with observations from Gaussian, Poisson, binomial, negative binomial, and gamma 
+    distributions. See the paper by Helske (2017) <doi:10.18637/jss.v078.i10> for details.
+License: GPL (>= 2)
+BugReports: https://github.com/helske/KFAS/issues
+VignetteBuilder: knitr
+Encoding: UTF-8
+ByteCompile: true
+URL: https://github.com/helske/KFAS
+RoxygenNote: 7.3.2

NAMESPACE

@@ -21,6 +21,7 @@ S3method(subset,SSModel)
 export("subset<-")
 export(KFS)
 export(SSMarima)
+export(SSMbespoke)
 export(SSMcustom)
 export(SSMcycle)
 export(SSModel)

R/KFAS-package.R

@@ -592,7 +592,7 @@
 #'
 #' }
 #'
-NULL
+"_PACKAGE"
 #' Oxford-Cambridge boat race results 1829-2011
 #'
 #' Results of the annual boat race between universities of Oxford (0) and Cambridge (1).

R/SSMbespoke.R

@@ -0,0 +1,34 @@
+#' @rdname SSModel
+#' @param f An user-defined function which should return the output from 
+#' \code{\link{SSMcustom}}. See examples.
+#' @examples
+#' # Example on bespoke function for time-varying trend
+#' trend <- function(sigma, n) {
+#'   Z <- array(seq_len(n), c(1, 1, n))
+#'   T <- R <- matrix(1, 1, 1)
+#'   Q <- matrix(sigma^2, 1, 1)
+#'   a1 <- 0
+#'   P1 <- 10
+#'   SSMcustom(Z, T, R, Q, a1, P1, n = n, state_names = "timevarying trend")
+#' }
+#' 
+#' model <- SSModel(Nile ~ SSMbespoke(trend(NA, length(Nile))), H = NA)
+#' updatefn <- function(pars, model){
+#'   model$Q[1, 1, 1] <- exp(0.5 * pars[1])
+#'   model$H[1, 1, 1] <- exp(0.5 * pars[2])
+#'   model
+#' }
+#' 
+#' fit <- fitSSM(model, c(1, 20), updatefn, method = "BFGS")
+#' conf_intv <- predict(fit$model, interval = "confidence", level = 0.95)
+#' 
+#' ts.plot(
+#'   cbind(Nile, conf_intv), 
+#'   col = c(1, 2, 2, 2),
+#'   ylab = "Predicted Annual flow", 
+#'   main = "River Nile"
+#' ) 
+#' @export
+SSMbespoke <- function(f, index, n) {
+  f
+}

R/SSModel.R

@@ -8,14 +8,19 @@
 #' functions defining different types of components of the model, named as
 #' \code{SSMarima}, \code{SSMcustom}, \code{SSMcycle}, \code{SSMregression},
 #' \code{SSMseasonal} and \code{SSMtrend}.
-#'
-#' For more details, see package vignette (the mathematical notation is somewhat non-readable in ASCII).
+#' 
+#' \code{SSMbespoke} function is similar to \code{\link{SSMcustom}} but instead 
+#' of defining the model component directly via system matrices, it wraps an 
+#' arbitrary user-defined function which should return the output from 
+#' \code{\link{SSMcustom}}.
+#' For more details, see package vignette.
 #'
 #' @export
 #' @importFrom stats terms update.formula drop.terms model.response model.matrix delete.response update.formula
 #' @rdname SSModel
 #' @name SSModel
-#' @seealso \code{\link{KFAS}} for more examples.
+#' @seealso \code{\link{KFAS}} for more examples and \code{link{SSMbespoke}} for 
+#'   an alternative way of creating custom components.
 #' @param formula An object of class \code{\link{formula}} containing the
 #'   symbolic description of the model. The intercept term can be removed with
 #'   \code{-1} as in \code{lm}. In case of trend or differenced arima component the
@@ -253,7 +258,7 @@ SSModel <- function(formula, data, H, u, distribution,
   mf[[1L]] <- as.name("model.frame")
   mf$na.action <- as.name("na.pass")
   components <- c("SSMregression", "SSMtrend", "SSMseasonal", "SSMcycle",
-    "SSMarima", "SSMcustom")
+    "SSMarima", "SSMcustom", "SSMbespoke")
 
   all_terms <- terms_out <- terms(formula, specials = components, data = data)
   specials <- attr(all_terms, "specials")