Merge pull request #67 from SebKrantz/development

Development

Author: SebKrantz

DESCRIPTION

@@ -3,17 +3,19 @@ Version: 0.3.0
 Title: Dynamic Factor Models
 Authors@R: c(person("Sebastian", "Krantz", role = c("aut", "cre"), email = "[email protected]"),
              person("Rytis", "Bagdziunas", role = "aut"),
-             person("Santtu", "Tikka", role = "rev"))
+             person("Santtu", "Tikka", role = "rev"),
+             person("Eli", "Holmes", role = "rev"))
 Description: Efficient estimation of Dynamic Factor Models using the Expectation Maximization (EM) algorithm 
-  or Two-Step (2S) estimation, supporting datasets with missing data. The estimation options follow advances in the 
-  econometric literature: either running the Kalman Filter and Smoother once with initial values from PCA - 
-  2S estimation as in Doz, Giannone and Reichlin (2011) <doi:10.1016/j.jeconom.2011.02.012> - or via iterated 
-  Kalman Filtering and Smoothing until EM convergence - following Doz, Giannone and Reichlin (2012) 
-  <doi:10.1162/REST_a_00225> - or using the adapted EM algorithm of Banbura and Modugno (2014) <doi:10.1002/jae.2306>, 
-  allowing arbitrary patterns of missing data. The implementation makes heavy use of the 'Armadillo' 'C++' library and 
-  the 'collapse' package, providing for particularly speedy estimation. A comprehensive set of methods supports 
-  interpretation and visualization of the model as well as forecasting. Information criteria to choose the number 
-  of factors are also provided - following Bai and Ng (2002) <doi:10.1111/1468-0262.00273>.
+  or Two-Step (2S) estimation, supporting datasets with missing data. Factors are assumed to follow a stationary VAR 
+  process of order p. The estimation options follow advances in the econometric literature: either running the Kalman 
+  Filter and Smoother once with initial values from PCA - 2S estimation as in Doz, Giannone and Reichlin (2011) 
+  <doi:10.1016/j.jeconom.2011.02.012> - or via iterated Kalman Filtering and Smoothing until EM convergence - following 
+  Doz, Giannone and Reichlin (2012) <doi:10.1162/REST_a_00225> - or using the adapted EM algorithm of Banbura and 
+  Modugno (2014) <doi:10.1002/jae.2306>, allowing arbitrary patterns of missing data. The implementation makes heavy 
+  use of the 'Armadillo' 'C++' library and the 'collapse' package, providing for particularly speedy estimation. 
+  A comprehensive set of methods supports interpretation and visualization of the model as well as forecasting. 
+  Information criteria to choose the number of factors are also provided - following Bai and Ng (2002) 
+  <doi:10.1111/1468-0262.00273>.
 URL: https://sebkrantz.github.io/dfms/
 BugReports: https://github.com/SebKrantz/dfms/issues
 Depends: R (>= 3.5.0)

R/DFM.R

@@ -147,7 +147,8 @@
 #' VARselect(IC_small$F_pca[, 1:2])
 #'
 #' # Estimating the model with 2 factors and 3 lags
-#' dfm_small = DFM(BM14[, BM14_Models$small], 2, 3)
+#' dfm_small = DFM(BM14[, BM14_Models$small], r = 2, p = 3,
+#'     quarterly.vars = BM14_Models %$% series[freq == "Q" & small])
 #'
 #' # Inspecting the model
 #' summary(dfm_small)
@@ -170,7 +171,8 @@
 #' VARselect(IC_medium$F_pca[, 1:3])
 #'
 #' # Estimating the model with 3 factors and 3 lags
-#' dfm_medium = DFM(BM14[, BM14_Models$medium], 3, 3)
+#' dfm_medium = DFM(BM14[, BM14_Models$medium], r = 3, p = 3,
+#'     quarterly.vars = BM14_Models %$% series[freq == "Q" & medium])
 #'
 #' # Inspecting the model
 #' summary(dfm_medium)
@@ -193,7 +195,8 @@
 #' VARselect(IC_large$F_pca[, 1:6])
 #'
 #' # Estimating the model with 6 factors and 3 lags
-#' dfm_large = DFM(BM14, 6, 3)
+#' dfm_large = DFM(BM14, r = 6, p = 3,
+#'     quarterly.vars = BM14_Models %$% series[freq == "Q"])
 #'
 #' # Inspecting the model
 #' summary(dfm_large)

R/dfms.R

@@ -1,55 +1,60 @@
 #' Dynamic Factor Models
 #'
-#' *dfms* provides efficient estimation of Dynamic Factor Models via the EM Algorithm.
+#' @description
 #'
-#' Estimation can be done in 3 different ways following:
+#' *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:
 #'
-#'  - Doz, C., Giannone, D., & Reichlin, L. (2011). A two-step estimator for large approximate dynamic factor models based on Kalman filtering. *Journal of Econometrics, 164*(1), 188-205. <doi:10.1016/j.jeconom.2011.02.012>
+#' **Information Criteria**
 #'
-#'  - Doz, C., Giannone, D., & Reichlin, L. (2012). A quasi-maximum likelihood approach for large, approximate dynamic factor models. *Review of Economics and Statistics, 94*(4), 1014-1024. <doi:10.1162/REST_a_00225>
-#'
-#'  - Banbura, M., & Modugno, M. (2014). Maximum likelihood estimation of factor models on datasets with arbitrary pattern of missing data. *Journal of Applied Econometrics, 29*(1), 133-160. <doi:10.1002/jae.2306>
-#'
-#'  The default is `em.method = "auto"`, which chooses `"BM"` following Banbura & Modugno (2014) with missing data or mixed frequency, and `"DGR"` following Doz, Giannone & Reichlin (2012) otherwise. Using `em.method = "none"` generates Two-Step estimates following Doz, Giannone & Reichlin (2011). This is extremely efficient on bigger datasets. PCA and Two-Step estimates are also reported in EM-estimation. All methods support missing data, but `em.method = "DGR"` does not model them in EM iterations.
-#'
-#' @section Package Contents:
-#'
-#' **Functions to Specify/Estimate Model and Key Methods**
-#'
-#'  \code{\link[=ICr]{ICr()}} --- Information Criteria\cr
+#'  \code{\link[=ICr]{ICr()}}\cr
 #'
 #'  - \code{\link[=plot.ICr]{plot(<ICr>)}}\cr
 #'  - \code{\link[=screeplot.ICr]{screeplot(<ICr>)}}\cr
 #'
-#'  \code{\link[=DFM]{DFM()}} --- Estimate the Model\cr
+#' **Fit a Dynamic Factor Model**
+#'
+#'  \code{\link[=DFM]{DFM()}}\cr
 #'
 #'  - \code{\link[=summary.dfm]{summary(<dfm>)}}\cr
 #'  - \code{\link[=plot.dfm]{plot(<dfm>)}}\cr
 #'  - \code{\link[=as.data.frame.dfm]{as.data.frame(<dfm>)}}\cr
 #'  - \code{\link[=residuals.dfm]{residuals(<dfm>)}}\cr
 #'  - \code{\link[=fitted.dfm]{fitted(<dfm>)}}
 #'
-#'  \code{\link[=predict.dfm]{predict(<dfm>)}} --- Generate Forecasts\cr
+#' **Generate Forecasts**
+#'
+#'  \code{\link[=predict.dfm]{predict(<dfm>)}}\cr
 #'
 #'  - \code{\link[=plot.dfm_forecast]{plot(<dfm_forecast>)}}\cr
 #'  - \code{\link[=as.data.frame.dfm_forecast]{as.data.frame(<dfm_forecast>)}}\cr
 #'
-#' **Auxiliary Functions**
+#' **Fast Stationary Kalman Filtering and Smoothing**
 #'
-#'  \code{\link[=.VAR]{.VAR()}} --- Estimate Vector Autoregression\cr
 #'  \code{\link[=SKF]{SKF()}} --- Stationary Kalman Filter\cr
 #'  \code{\link[=FIS]{FIS()}} --- Fixed Interval Smoother\cr
 #'  \code{\link[=SKFS]{SKFS()}} --- Stationary Kalman Filter + Smoother\cr
+#'
+#'  **Helper Functions**
+#'
+#'  \code{\link[=.VAR]{.VAR()}} --- (Fast) Barebones Vector-Autoregression\cr
+#'  \code{\link[=ainv]{ainv()}} --- Armadillo's Inverse Function\cr
+#'  \code{\link[=apinv]{apinv()}} --- Armadillo's Pseudo-Inverse Function\cr
 #'  \code{\link[=tsnarmimp]{tsnarmimp()}} --- Remove and Impute Missing Values in a Multivariate Time Series\cr
-#'  \code{\link[=ainv]{ainv()}} --- Rcpp Armadillo's Inverse Function\cr
-#'  \code{\link[=apinv]{apinv()}} --- Rcpp Armadillo's Pseudo-Inverse Function\cr
+#'  \code{\link[=em_converged]{em_converged()}} --- Convergence Test for EM-Algorithm\cr
 #'
 #' **Data**
 #'
 #'  \code{\link{BM14_M}} --- Monthly Series by Banbura and Modugno (2014)\cr
 #'  \code{\link{BM14_Q}} --- Quarterly Series by Banbura and Modugno (2014)\cr
 #'  \code{\link{BM14_Models}} --- Series Metadata + Small/Medium/Large Model Specifications\cr
 #'
+#' @references
+#' Doz, C., Giannone, D., & Reichlin, L. (2011). A two-step estimator for large approximate dynamic factor models based on Kalman filtering. *Journal of Econometrics, 164*(1), 188-205. <doi:10.1016/j.jeconom.2011.02.012>
+#'
+#' Doz, C., Giannone, D., & Reichlin, L. (2012). A quasi-maximum likelihood approach for large, approximate dynamic factor models. *Review of Economics and Statistics, 94*(4), 1014-1024. <doi:10.1162/REST_a_00225>
+#'
+#' Banbura, M., & Modugno, M. (2014). Maximum likelihood estimation of factor models on datasets with arbitrary pattern of missing data. *Journal of Applied Econometrics, 29*(1), 133-160. <doi:10.1002/jae.2306>
+#'
 #' @docType package
 #' @name dfms-package
 #' @aliases dfms

R/methods.R

@@ -457,7 +457,7 @@ fitted.dfm <- function(object,
 #' @param method character. The factor estimates to use: one of \code{"qml"}, \code{"2s"} or \code{"pca"}.
 #' @param standardized logical. \code{FALSE} will return data forecasts on the original scale.
 #' @param resFUN an (optional) function to compute a univariate forecast of the residuals.
-#' The function needs to have a second argument providing the forecast horizon (\code{h}) and return a vector or forecasts. See Examples.
+#' The function needs to have a second argument providing the forecast horizon (\code{h}) and return a vector of forecasts. See Examples.
 #' @param resAC numeric. Threshold for residual autocorrelation to apply \code{resFUN}: only residual series where AC1 > resAC will be forecasted.
 #' @param \dots further arguments to \code{resFUN}.
 #'

README.md

@@ -17,7 +17,8 @@
 <!--
 The package is fully functional though, and you are very welcome to install it using `remotes::install_github("SebKrantz/dfms")` and give feedback. -->
 
-*dfms* provides efficient estimation of Dynamic Factor Models via the EM Algorithm. Estimation can be done in 3 different ways following:
+*dfms* provides efficient estimation of Dynamic Factor Models via the EM Algorithm. Factors are assumed to follow a stationary VAR 
+  process of order `p`. Estimation can be done in 3 different ways following:
 
 - Doz, C., Giannone, D., & Reichlin, L. (2011). A two-step estimator for large approximate dynamic factor models based on Kalman filtering. *Journal of Econometrics, 164*(1), 188-205. <doi:10.1016/j.jeconom.2011.02.012> 
 
@@ -27,7 +28,7 @@ The package is fully functional though, and you are very welcome to install it u
 
 The default is `em.method = "auto"`, which chooses `"BM"` following Banbura & Modugno (2014) with missing data or mixed frequency, and `"DGR"` following Doz, Giannone & Reichlin (2012) otherwise. Using `em.method = "none"` generates Two-Step estimates following Doz, Giannone & Reichlin (2011). This is extremely efficient on bigger datasets. PCA and Two-Step estimates are also reported in EM-estimation. All methods support missing data, but `em.method = "DGR"` does not model them in EM iterations.
 
-The package is stable, but functionality may expand in the future. In particular, mixed-frequency estimation with autoregressive errors is planned for the near future, and generation of the 'news' may be added in the further future. 
+The package is currently stable, but functionality may expand in the future. In particular, mixed-frequency estimation with autoregressive errors is planned for the near future, and generation of the 'news' may be added in the further future. 
 
 
 ### Comparison with Other R Packages
@@ -56,7 +57,7 @@ install.packages('dfms', repos = c('https://sebkrantz.r-universe.dev', 'https://
 library(dfms)
 
 # Fit DFM with 6 factors and 3 lags in the transition equation
-mod = DFM(diff(BM14_M), r = 6, p = 3) 
+mod <- DFM(diff(BM14_M), r = 6, p = 3) 
 ```
 
 ```
@@ -139,7 +140,7 @@ plot(mod)
 ```
 
 <div class="figure">
-<img src="misc/figure/unnamed-chunk-1-1.png" alt="plot of chunk unnamed-chunk-1" width="100%" />
+<img src="https://raw.githubusercontent.com/SebKrantz/dfms/main/misc/figure/unnamed-chunk-1-1.png" alt="plot of chunk unnamed-chunk-1" width="100%" />
 </div>
 
 ```r
@@ -158,14 +159,14 @@ as.data.frame(mod) |> head()
 
 ```r
 # Forecasting 20 periods ahead
-fc = predict(mod, h = 20)
+fc <- predict(mod, h = 20)
 
 # 'dfm_forecast' methods
 plot(fc)
 ```
 
 <div class="figure">
-<img src="misc/figure/unnamed-chunk-1-2.png" alt="plot of chunk unnamed-chunk-1" width="100%" />
+<img src="https://raw.githubusercontent.com/SebKrantz/dfms/main/misc/figure/unnamed-chunk-1-2.png" alt="plot of chunk unnamed-chunk-1" width="100%" />
 </div>
 
 ```r