misspecification test update

R/RcppExports.R

@@ -25,8 +25,8 @@ IterativeKleibergenPaap2006BetaRankTestCpp <- function(returns, factors, target_
     .Call(`_intrinsicFRP_IterativeKleibergenPaap2006BetaRankTestCpp`, returns, factors, target_level)
 }
 
-HJMisspecificationTestCpp <- function(returns, factors, hac_prewhite = FALSE) {
-    .Call(`_intrinsicFRP_HJMisspecificationTestCpp`, returns, factors, hac_prewhite)
+HJMisspecificationTestCpp <- function(returns, factors, sqhj_distance_null_value = 0., hac_prewhite = FALSE) {
+    .Call(`_intrinsicFRP_HJMisspecificationTestCpp`, returns, factors, sqhj_distance_null_value, hac_prewhite)
 }
 
 OracleTFRPGCVCpp <- function(returns, factors, covariance_factors_returns, variance_returns, mean_returns, penalty_parameters, weighting_type = 'c', one_stddev_rule = FALSE, gcv_scaling_n_assets = FALSE, gcv_identification_check = FALSE, target_level_kp2006_rank_test = 0.05, relaxed = FALSE, include_standard_errors = FALSE, hac_prewhite = FALSE) {

R/frp.R

@@ -4,7 +4,7 @@
 ######  Factor Risk Premia ########
 ###################################
 
-#' Compute factor risk premia from data
+#' @title Factor risk premia.
 #'
 #' @name FRP
 #' @description Computes the Fama-MachBeth (1973) <doi:10.1086/260061> factor
@@ -13,41 +13,58 @@
 #' `beta = Cov[R, F] * V[F]^{-1}`
 #' or the misspecification-robust factor risk premia of Kan-Robotti-Shanken (2013)
 #' <doi:10.1111/jofi.12035>:
-#' `KRSFRP = (beta' * V[R]^{-1} * beta)^{-1} * beta' * V[R]^{-1} * E[R]`
+#' `KRSFRP = (beta' * V[R]^{-1} * beta)^{-1} * beta' * V[R]^{-1} * E[R]`,
 #' from data on factors `F` and test
-#' asset excess returns `R`. Optionally computes the corresponding
+#' asset excess returns `R`.
+#' These notions of factor risk premia are by construction the negative
+#' covariance of factors `F` with candidate SDF
+#' `M = 1 - d' * (F - E[F])`,
+#' where SDF coefficients `d` are obtained by minimizing pricing errors:
+#' `argmin_{d} (E[R] - Cov[R,F] * d)' * (E[R] - Cov[R,F] * d)`
+#' and
+#' `argmin_{d} (E[R] - Cov[R,F] * d)' * V[R]^{-1} * (E[R] - Cov[R,F] * d)`,
+#' respectively.
+#' Optionally computes the corresponding
 #' heteroskedasticity and autocorrelation robust standard errors using the
 #' Newey-West (1994) <doi:10.2307/2297912> plug-in procedure to select the
 #' number of relevant lags, i.e., `n_lags = 4 * (n_observations/100)^(2/9)`.
+#' For the standard error computations, the function allows to internally
+#' pre-whiten the series by fitting a VAR(1),
+#' i.e., a vector autoregressive model of order 1.
+#' All the details can be found in Kan-Robotti-Shanken (2013)
+#' <doi:10.1111/jofi.12035>.
 #'
-#' @param returns `n_observations x n_returns`-dimensional matrix of test asset
+#' @param returns A `n_observations x n_returns`-dimensional matrix of test asset
 #' excess returns.
-#' @param factors `n_observations x n_factors`-dimensional matrix of factors.
-#' @param misspecification_robust boolean `TRUE` for the
+#' @param factors A `n_observations x n_factors`-dimensional matrix of factors.
+#' @param misspecification_robust A boolean: `TRUE` for the
 #' "misspecification-robust" Kan-Robotti-Shanken (2013) GLS approach using the
 #' inverse covariance matrix of returns; `FALSE` for standard Fama-MacBeth
 #' risk premia. Default is `TRUE`.
-#' @param include_standard_errors boolean `TRUE` if you want to compute the
+#' @param include_standard_errors A boolean: `TRUE` if you want to compute the
 #' factor risk premia HAC standard errors; `FALSE` otherwise.
 #' Default is `FALSE`.
-#' @param hac_prewhite A boolean indicating if the series needs prewhitening by
+#' @param hac_prewhite A boolean indicating if the series needs pre-whitening by
 #' fitting an AR(1) in the internal heteroskedasticity and autocorrelation
 #' robust covariance (HAC) estimation. Default is `false`.
-#' @param target_level_gkr2014_screening Number indicating the target level of
+#' @param target_level_gkr2014_screening A number indicating the target level of
 #' the tests underlying the factor screening procedure in Gospodinov-Kan-Robotti
-#' (2014). If it's zero, then no factor screening procedure is
+#' (2014). If it is zero, then no factor screening procedure is
 #' implemented. Otherwise, it implements an iterative screening procedure
 #' based on the sequential removal of factors associated with the smallest insignificant
 #' t-test of a nonzero SDF coefficient. The threshold for the absolute t-test is
 #' `target_level_gkr2014_screening / n_factors`, where n_factors indicate the
-#' number of factors in the model at the current iteration. Default is `0.`.
-#' @param check_arguments boolean `TRUE` for internal check of all function
+#' number of factors in the model at the current iteration. Default is `0.`, i.e.,
+#' no factor screening.
+#' @param check_arguments A boolean: `TRUE` for internal check of all function
 #' arguments; `FALSE` otherwise. Default is `TRUE`.
 #'
-#' @return a list containing `n_factors`-dimensional vector of factor
-#' risk premia in `"risk_premia"`; if `include_standard_errors=TRUE`, then
+#' @return A list containing `n_factors`-dimensional vector of factor
+#' risk premia in `"risk_premia"`; if `include_standard_errors = TRUE`, then
 #' it further includes `n_factors`-dimensional vector of factor risk
-#' premia standard errors in `"standard_errors"`.
+#' premia standard errors in `"standard_errors"`;
+#' if `target_level_gkr2014_screening >= 0`, it further includes the indices of
+#' the selected factors in `selected_factor_indices`.
 #'
 #' @examples
 #' # import package data on 6 risk factors and 42 test asset excess returns

R/gkr_factor_screening.R

@@ -4,24 +4,26 @@
 ######  GKRFactorScreeening #######
 ###################################
 
-#' Perform the factor screening procedure of Gospodinov-Kan-Robotti (2014)
-#' from moments extracted from data
+#' @title Factor screening procedure of Gospodinov-Kan-Robotti (2014)
 #'
 #' @name GKRFactorScreening
 #' @description Performs the factor screening procedure of
 #' Gospodinov-Kan-Robotti (2014) <doi:10.2139/ssrn.2579821>, which is
-#' an iterative screening procedure
+#' an iterative model screening procedure
 #' based on the sequential removal of factors associated with the smallest insignificant
 #' t-test of a nonzero misspecification-robust SDF coefficient. The significance threshold for the
-#' absolute t-test is given by `target_level_gkr2014_screening / n_factors`,
-#' where n_factors indicate the number of factors in the model at the current iteration;
+#' absolute t-test is set to `target_level / n_factors`,
+#' where n_factors indicates the number of factors in the model at the current iteration;
 #' that is, it takes care of the multiple testing problem via a conservative
 #' Bonferroni correction. Standard errors are computed with the
-#' heteroskedasticity and autocorrelation using the Newey-West estimator.
-#' The number is selected using the Newey-West (1994)
-#' <doi:10.2307/2297912> plug-in procedure, where
+#' heteroskedasticity and autocorrelation using the Newey-West (1994)
+#' <doi:10.2307/2297912> estimator, where the number of lags
+#' is selected using the Newey-West plug-in procedure:
 #' `n_lags = 4 * (n_observations/100)^(2/9)`.
-#' The function allows to internally prewhiten the series by fitting a VAR(1).
+#' For the standard error computations, the function allows to internally
+#' pre-whiten the series by fitting a VAR(1),
+#' i.e., a vector autoregressive model of order 1.
+#' All the details can be found in Gospodinov-Kan-Robotti (2014) <doi:10.2139/ssrn.2579821>.
 #'
 #' @param returns `n_observations x n_returns`-dimensional matrix of test asset
 #' excess returns.
@@ -39,8 +41,10 @@
 #' @param check_arguments boolean `TRUE` for internal check of all function
 #' arguments; `FALSE` otherwise. Default is `TRUE`.
 #'
-#' @return A list contaning the GKR SDF coefficients, their standard errors and
-#' squared t-statistics. It further contain the indices of the selected factors.
+#' @return A list contaning the selected GKR SDF coefficients in `SDF_coefficients`,
+#' their standard errors in `standard_errors`,
+#' t-statistics in `t_statistics` and indices in the columns of the factor matrix `factors`
+#' supplied by the user in `selected_factor_indices`.
 #'
 #' @examples
 #' # import package data on 6 risk factors and 42 test asset excess returns
@@ -70,11 +74,16 @@ GKRFactorScreening = function(
   }
 
   # Perform the GKR factor screening procedure.
-  return(.Call(`_intrinsicFRP_GKRFactorScreeningCpp`,
+  results = .Call(`_intrinsicFRP_GKRFactorScreeningCpp`,
     returns,
     factors,
     target_level,
     hac_prewhite
-  ))
+  )
+
+  # Transform c++ indices (starting at 0) into R indices (starting at 1).
+  results$selected_factor_indices = results$selected_factor_indices + 1
+
+  return(results)
 
 }

R/hac_covariance.R

@@ -7,18 +7,22 @@
 
 #' @title Heteroskedasticity and Autocorrelation robust covariance estimator
 #'
+#' @name HACcovariance
 #' @description This function estimates the long-run covariance matrix of a multivariate
 #' centred time series accounting for heteroskedasticity and autocorrelation
 #' using the Newey-West estimator.
 #' The number of lags is selected using the Newey-West (1994)
 #' <doi:10.2307/2297912> plug-in procedure, where
 #' `n_lags = 4 * (n_observations/100)^(2/9)`.
-#' The function allows to internally prewhiten the series by fitting a VAR(1).
+#' The function allows to internally prewhiten the series by fitting a VAR(1),
+#' i.e., a vector autoregressive model of order 1.
+#' All the details can be found in Newey-West (1994)
+#' <doi:10.2307/2297912>.
 #'
 #' @param series A matrix (or vector) of data where each column is a time series.
 #' @param prewhite A boolean indicating if the series needs prewhitening by
 #' fitting an AR(1). Default is `FALSE`
-#' @param check_arguments boolean `TRUE` for internal check of all function
+#' @param check_arguments A boolean `TRUE` for internal check of all function
 #' arguments; `FALSE` otherwise. Default is `TRUE`.
 #'
 #' @return A symmetric matrix (or a scalar if only one column series is provided)

R/identification_tests.R

@@ -6,6 +6,7 @@
 
 #' @title Asset Pricing Model Identification via Chen-Fang (2019) Beta Rank Test
 #'
+#' @name ChenFang2019BetaRankTest
 #' @description Tests the null hypothesis of reduced rank in the matrix of regression
 #' loadings for test asset excess returns on risk factors using the Chen-Fang (2019)
 #' <doi:10.3982/QE1139>
@@ -16,6 +17,8 @@
 #' `target_level_kp2006_rank_test <= 0`, the number of singular values above
 #' `n_observations^(-1/4)` is used instead. It presumes that the number of factors
 #' is less than the number of returns (`n_factors < n_returns`).
+#' All the details can be found in Chen-Fang (2019)
+#' <doi:10.3982/QE1139>.
 #'
 #' @param returns Matrix of test asset excess returns with dimensions `n_observations x n_returns`.
 #' @param factors Matrix of risk factors with dimensions `n_observations x n_factors`.
@@ -67,14 +70,16 @@ ChenFang2019BetaRankTest = function(
 
 }
 
-#' @title Iterative Kleibergen-Paap 2006 Beta Rank Test for Asset Pricing Models
+#' @title Asset Pricing Model Identification via Iterative Kleibergen-Paap 2006 Beta Rank Test
 #'
+#' @name IterativeKleibergenPaap2006BetaRankTest
 #' @description Evaluates the rank of regression loadings in an asset pricing model using the
 #' iterative Kleibergen-Paap (2006) <doi:10.1016/j.jeconom.2005.02.011> beta rank test.
 #' It systematically tests the null hypothesis
 #' for each potential rank `q = 0, ..., n_factors - 1` and estimates the rank as the smallest `q`
 #' that has a p-value below the significance level, adjusted for the number of factors.
 #' The function presupposes more returns than factors (`n_factors < n_returns`).
+#' All the details can be found in Kleibergen-Paap (2006) <doi:10.1016/j.jeconom.2005.02.011>.
 #'
 #' @param returns A matrix of test asset excess returns with dimensions `n_observations x n_returns`.
 #' @param factors A matrix of risk factors with dimensions `n_observations x n_factors`.

R/misspecification_test.R

@@ -5,30 +5,40 @@
 #########################################
 
 
-#' @title Asset Prciing HJ model misspecification test
+#' @title Compute the HJ asset pricing model misspecification test.
 #'
-#' @description Computes the Hansen-Jagannathan (1997) <doi:10.1111/j.1540-6261.1997.tb04813.x>
-#' model misspecification statistic and
-#' p-value of an asset pricing model from test asset excess returns `R` and
-#' risk factors `F`. The statistic is defined as:
-#' `HJDISTANCE = min_{d} (E[R] - beta * d)' * Var[R]^{-1} * (E[R] - beta * d)`
-#' where `beta = Cov[R, F] * Var[F]^{-1}` are the regression coefficients of
-#' test asset excess returns `R` on risk factors `F`.
-#' Detailed computations and p-value calculations can be found in
-#' Kan-Robotti (2008) <10.1016/j.jempfin.2008.03.003>.
+#' @name HJMisspecificationTest
+#' @description Computes and tests the Kan-Robotti (2008) <10.1016/j.jempfin.2008.03.003>
+#' squared model misspecification distance:
+#' `sqhj_distance = min_{d} (E[R] - Cov[R,F] * d)' * V[R]^{-1} * (E[R] - Cov[R,F] * d)`,
+#' where `R` denotes test asset excess returns and `F` risk factors.
+#' This model misspecification distance is a modification of the prominent
+#' Hansen-Jagannathan (1997) <doi:10.1111/j.1540-6261.1997.tb04813.x>
+#' distance, adapted to the use of excess returns for the test asset, and a
+#' SDF that is a linear function of demeaned factors.
+#' The Null Hypothesis of the test is:
+#' `H0: sqhj_distance = sqhj_distance_null_value`,
+#' where `sqhj_distance_null_value` is the user-supplied hypothesized value of
+#' the squared model misspecification distance.
+#' Computation of the p-values is obtained with asymptotic analysis under
+#' misspecified models; that is, without assuming correct specification.
+#' Details can be found in Kan-Robotti (2008) <10.1016/j.jempfin.2008.03.003>.
 #'
-#' @param returns An `n_observations x n_returns`-dimensional matrix of test asset
-#' excess returns.
-#' @param factors An `n_observations x n_factors`-dimensional matrix of risk
-#' factors.
-#' @param hac_prewhite A boolean indicating if the series needs prewhitening by
+#' @param returns A `n_observations x n_returns` matrix of test asset excess returns.
+#' @param factors A `n_observations x n_factors` matrix of risk factors.
+#' @param sqhj_distance_null_value A number indicating the testing value under
+#' the null hypothesisfor the squared HJ model-misspecification distance.
+#' Default is zero.
+#' @param hac_prewhite A boolean indicating if the series needs pre-whitening by
 #' fitting an AR(1) in the internal heteroskedasticity and autocorrelation
 #' robust covariance (HAC) estimation. Default is `false`.
-#' @param check_arguments A boolean `TRUE` if you want to check function arguments;
-#' `FALSE` otherwise. Default is `TRUE`.
+#' @param check_arguments A boolean: `TRUE` for internal check of all function
+#' arguments; `FALSE` otherwise. Default is `TRUE`.
 #'
-#' @return A list containing the squared standardized HJ test statistic and
-#' the corresponding p-value.
+#' @return @return A list containing the squared misspecification-robust HJ
+#' distance, the associated standardized test statistic
+#' `T * (sqhj_distance - sqhj_distance_null_value)^2 / AsySdErr(sqhj_distance)`
+#' and the corresponding p-value.
 #'
 #' @examples
 #' # Import package data on 6 risk factors and 42 test asset excess returns
@@ -42,6 +52,7 @@
 HJMisspecificationTest = function(
   returns,
   factors,
+  sqhj_distance_null_value = 0.,
   hac_prewhite = FALSE,
   check_arguments = TRUE
 ) {
@@ -50,6 +61,8 @@ HJMisspecificationTest = function(
   if (check_arguments) {
 
     CheckData(returns, factors)
+    stopifnot("`sqhj_distance_null_value` must be numeric" = is.numeric(sqhj_distance_null_value))
+    stopifnot("`sqhj_distance_null_value` must be greater or equal to zero" = sqhj_distance_null_value >= 0.)
     stopifnot("`hac_prewhite` must be boolean" = is.logical(hac_prewhite))
 
   }
@@ -58,6 +71,7 @@ HJMisspecificationTest = function(
   return(.Call(`_intrinsicFRP_HJMisspecificationTestCpp`,
     returns,
     factors,
+    sqhj_distance_null_value,
     hac_prewhite
   ))