Merge pull request #68 from SebKrantz/development

Development

Author: SebKrantz

.Rbuildignore

@@ -1,6 +1,7 @@
 ^dfms\.Rproj$
 ^\.Rproj\.user$
 misc
+^README\.html$
 .RData
 LICENSE
 ^\.github$

.gitignore

@@ -53,3 +53,4 @@ vignettes/*.pdf
 .Rproj.user
 # docs
 inst/doc
+docs

NAMESPACE

@@ -2,7 +2,9 @@
 
 S3method(as.data.frame,dfm)
 S3method(as.data.frame,dfm_forecast)
+S3method(coef,dfm)
 S3method(fitted,dfm)
+S3method(logLik,dfm)
 S3method(plot,ICr)
 S3method(plot,dfm)
 S3method(plot,dfm_forecast)

R/DFM.R

@@ -11,14 +11,14 @@
 #' Efficient estimation of a Dynamic Factor Model via the EM Algorithm - on stationary data
 #' with time-invariant system matrices and classical assumptions, while permitting missing data.
 #'
-#' @param X a \code{T x n} numeric data matrix or frame of stationary time series. May contain missing values.
-#' @param r integer. number of factors.
-#' @param p integer. number of lags in factor VAR.
-#' @param \dots (optional) arguments to \code{\link{tsnarmimp}}.
-#' @param idio.ar1 logical. Model observation errors as AR(1) processes: \eqn{e_t = \rho e_{t-1} + v_t}{e(t) = rho e(t-1) + v(t)}. \emph{Note} that this substantially increases computation time, and is generaly not needed if \code{n} is large (>30). See theoretical vignette for details.
+#' @param X a \code{T x n} numeric data matrix or frame of stationary time series. May contain missing values. \emph{Note} that data is internally standardized (scaled and centered) before estimation.
+#' @param r integer. Number of factors.
+#' @param p integer. Number of lags in factor VAR.
+#' @param \dots (optional) arguments to \code{\link{tsnarmimp}}. The default settings impute internal missing values with a cubic spline and the edges with the median and a 3-period moving average.
+#' @param idio.ar1 logical. Model observation errors as AR(1) processes: \eqn{e_t = \rho e_{t-1} + v_t}{e(t) = rho e(t-1) + v(t)}. \emph{Note} that this substantially increases computation time, and is generally not needed if \code{n} is large (>30). See theoretical vignette for details.
 #' @param quarterly.vars character. Names of quarterly variables in \code{X} (if any). Monthly variables should be to the left of the quarterly variables in the data matrix and quarterly observations should be provided every 3rd period.
-#' @param rQ character. restrictions on the state (transition) covariance matrix (Q).
-#' @param rR character. restrictions on the observation (measurement) covariance matrix (R).
+#' @param rQ character. Restrictions on the state (transition) covariance matrix (Q).
+#' @param rR character. Restrictions on the observation (measurement) covariance matrix (R).
 #' @param em.method character. The implementation of the Expectation Maximization Algorithm used. The options are:
 #'    \tabular{llll}{
 #' \code{"auto"} \tab\tab Automatic selection: \code{"BM"} if \code{anyNA(X)}, else \code{"DGR"}. \cr\cr
@@ -77,9 +77,11 @@
 #'  \eqn{\textbf{R}}{R} \tab\tab \eqn{n \times n}{n x n} observation covariance matrix. It is diagonal by assumption 2 and identical to \eqn{\textbf{R}}{R} as stated in the dynamic form.\cr\cr
 #' }
 #  that \eqn{E[\textbf{f}_t|\textbf{F}_{t-1}] = E[\textbf{f}_t|\textbf{f}_{t-1}] = \textbf{A}_1 \textbf{f}_{t-1}}{E[f(t)|F(t-1)] = E[f(t)|f(t-1)] = A1 f(t-1)} (all relationships between lagged factors are captured in \eqn{\textbf{A}_1}{A1}).\cr\cr
+#' The filter is initialized with PCA estimates on the imputed dataset---see \code{\link{SKFS}} for a complete code example.
+#'
 #'
 #' @returns A list-like object of class 'dfm' with the following elements:
-#'  \item{\code{X_imp}}{\eqn{T \times n}{T x n} matrix with the imputed and standardized (scaled and centered) data - with attributes attached allowing reconstruction of the original data:
+#'  \item{\code{X_imp}}{\eqn{T \times n}{T x n} matrix with the imputed and standardized (scaled and centered) data---after applying \code{\link{tsnarmimp}}. It has attributes attached allowing for reconstruction of the original data:
 #'  \tabular{llll}{
 #'      \code{"stats"} \tab\tab is a \eqn{n \times 5}{n x 5} matrix of summary statistics of class \code{"qsu"} (see \code{\link[collapse]{qsu}}).\cr\cr
 #'      \code{"missing"} \tab\tab is a \eqn{T \times n}{T x n} logical matrix indicating missing or infinite values in the original data (which are imputed in \code{X_imp}).\cr\cr
@@ -104,6 +106,7 @@
 #'  \item{\code{converged}}{single logical valued indicating whether the EM algorithm converged (within \code{max.iter} iterations subject to \code{tol}).}
 #'  \item{\code{anyNA}}{single logical valued indicating whether there were any (internal) missing values in the data (determined after removal of rows with too many missing values). If \code{FALSE}, \code{X_imp} is simply the original data in matrix form, and does not have the \code{"missing"} attribute attached.}
 #'  \item{\code{rm.rows}}{vector of any cases (rows) that were removed beforehand (subject to \code{max.missing} and \code{na.rm.method}). If no cases were removed the slot is \code{NULL}. }
+#'  \item{\code{quarterly.vars}}{names of the quarterly variables (if any).}
 #'  \item{\code{em.method}}{The EM method used.}
 #'  \item{\code{call}}{call object obtained from \code{match.call()}.}
 #'

R/dfms.R

@@ -2,9 +2,9 @@
 #'
 #' @description
 #'
-#' *dfms* provides efficient estimation of Dynamic Factor Models via the EM Algorithm --- following Doz, Giannone & Reichlin (2011, 2012) and Banbura & Modugno (2014). The package has the following contents:
+#' *dfms* provides efficient estimation of Dynamic Factor Models via the EM Algorithm --- following Doz, Giannone & Reichlin (2011, 2012) and Banbura & Modugno (2014). Contents:
 #'
-#' **Information Criteria**
+#' **Information Criteria to Determine the Number of Factors**
 #'
 #'  \code{\link[=ICr]{ICr()}}\cr
 #'

R/methods.R

@@ -43,8 +43,8 @@
 #'
 #' @title DFM Summary Methods
 #'
-#' @description Summary and print methods for class 'dfm'. \code{print.dfm} just prints basic model information and the factor transition matrix \eqn{\textbf{A}}{A},
-#' \code{summary.dfm} returns all system matrices and additional residual and goodness of fit statistics - with a print method allowing full or compact printout.
+#' @description Summary and print methods for class 'dfm'. \code{print.dfm} just prints basic model information and the factor transition matrix \eqn{\textbf{A}}{A}, \code{coef.dfm} returns \eqn{\textbf{A}}{A} and \eqn{\textbf{C}}{C} in a plain list, whereas
+#' \code{summary.dfm} returns all system matrices and additional residual and goodness of fit statistics---with a print method allowing full or compact printout.
 #'
 #' @param x,object an object class 'dfm'.
 #' @param digits integer. The number of digits to print out.
@@ -73,10 +73,18 @@ print.dfm <- function(x, digits = 4L, ...) {
   return(invisible(x))
 }
 
+#' @rdname summary.dfm
+#' @export
+coef.dfm <- function(object, ...) list(A = object$A, C = object$C)
+
+#' @rdname summary.dfm
+#' @export
+logLik.dfm <- function(object, ...) object$loglik[length(object$loglik)]
+
 #' @rdname summary.dfm
 #' @param method character. The factor estimates to use: one of \code{"qml"}, \code{"2s"} or \code{"pca"}.
 #' @param \dots not used.
-#' @return Summary information following a dynamic factor model estimation.
+#' @return Summary information following a dynamic factor model estimation. \code{coef()} returns \eqn{\textbf{A}}{A} and \eqn{\textbf{C}}{C}.
 #' @importFrom stats cov
 #' @importFrom collapse pwcov
 #' @export

R/my_RcppExports.R

@@ -4,7 +4,7 @@ Estep <- function(X, A, C, Q, R, F_0, P_0) {
 
 #' (Fast) Stationary Kalman Filter
 #'
-#' @description A simple and fast C++ implementation of the Kalman Filter for stationary data with time-invariant system matrices and missing data.
+#' @description A simple and fast C++ implementation of the Kalman Filter for stationary data (or random walks - data should be mean zero and without a trend) with time-invariant system matrices and missing data.
 #' @param X numeric data matrix (\eqn{T \times n}{T x n}).
 #' @param A transition matrix (\eqn{rp \times rp}{rp x rp}).
 #' @param C observation matrix (\eqn{n \times rp}{n x rp}).
@@ -103,7 +103,7 @@ FIS <- function(A, F, F_pred, P, P_pred, F_0 = NULL, P_0 = NULL) {
 #' @inheritParams SKF
 #'
 #' @returns All results from \code{\link{SKF}} and \code{\link{FIS}}, and additionally
-#' a \eqn{rp \times rp \times T}{rp x rp x T} matrix \code{PPm_smooth}, which is equal to the estimate of \eqn{Cov(F^smooth_t, F^smooth_{t-1} | T)}{Cov(F_smooth(t), F_smooth(t-1) | T)} and needed for EM iterations.
+#' a \eqn{rp \times rp \times T}{rp x rp x T} matrix \code{PPm_smooth}, which is equal to the estimate of \eqn{Cov(F^{smooth}_t, F^{smooth}_{t-1} | T)}{Cov(F_smooth(t), F_smooth(t-1) | T)} and needed for EM iterations.
 #' See 'Property 6.3: The Lag-One Covariance Smoother' in Shumway & Stoffer (2017).
 #'
 #'

_pkgdown.yml

@@ -93,10 +93,10 @@ external-articles:
 
 articles:
   - title: Introduction to dfms
-    desc: Provides a walk-through of all main features
+    desc: Introduces the package, including a walk-through of all main features.
     contents:
     - introduction
   - title: Dynamic Factor Models - A Very Short Introduction
-    desc: Provides a short theoretical overview of dynamics factor models as used in the economics literature
+    desc: Provides a short overview of dynamics factor models as used in the economics literature.
     contents:
     - dynamic_factor_models