implement HJMisspecificationDistance

NAMESPACE

@@ -4,7 +4,7 @@ export(ChenFang2019BetaRankTest)
 export(FRP)
 export(GKRFactorScreening)
 export(HACcovariance)
-export(HJMisspecificationTest)
+export(HJMisspecificationDistance)
 export(IterativeKleibergenPaap2006BetaRankTest)
 export(OracleTFRP)
 export(TFRP)

NEWS.md

@@ -13,3 +13,11 @@
 * Function `AdaptiveIFRP` deleted.
 * Function `ChenFang2019BetaRankTest` added.
 * Function `HJMisspecificationTest` added.
+
+# intrinsicFRP 1.0.1
+
+* Function `HJMisspecificationTest` adapted to the use of excess returns.
+* Function `IterativeKleibergenPaap2006BetaRankTest` added.
+* Function `GKRFactorScreening` added.
+* Function `HACcovariance` added.
+* Function `HJMisspecificationTest` extended and renamed `HJMisspecificationDistance`.

R/RcppExports.R

@@ -17,6 +17,10 @@ HACVarianceCpp <- function(series, prewhite = FALSE) {
     .Call(`_intrinsicFRP_HACVarianceCpp`, series, prewhite)
 }
 
+HJMisspecificationDistanceCpp <- function(returns, factors, ci_coverage = .95, hac_prewhite = FALSE) {
+    .Call(`_intrinsicFRP_HJMisspecificationDistanceCpp`, returns, factors, ci_coverage, hac_prewhite)
+}
+
 ChenFang2019BetaRankTestCpp <- function(returns, factors, n_bootstrap = 500L, target_level_kp2006_rank_test = 0.05) {
     .Call(`_intrinsicFRP_ChenFang2019BetaRankTestCpp`, returns, factors, n_bootstrap, target_level_kp2006_rank_test)
 }
@@ -25,10 +29,6 @@ IterativeKleibergenPaap2006BetaRankTestCpp <- function(returns, factors, target_
     .Call(`_intrinsicFRP_IterativeKleibergenPaap2006BetaRankTestCpp`, returns, factors, target_level)
 }
 
-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) {
     .Call(`_intrinsicFRP_OracleTFRPGCVCpp`, returns, factors, covariance_factors_returns, variance_returns, mean_returns, penalty_parameters, weighting_type, one_stddev_rule, gcv_scaling_n_assets, gcv_identification_check, target_level_kp2006_rank_test, relaxed, include_standard_errors, hac_prewhite)
 }

R/hac_covariance.R

@@ -10,12 +10,11 @@
 #' @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
+#' using the Newey-West (1994)
+#' <doi:10.2307/2297912> estimator.
+#' The number is selected using the Newey-West 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),
-#' i.e., a vector autoregressive model of order 1.
+#' The function allows to internally prewhiten the series by fitting a VAR(1).
 #' All the details can be found in Newey-West (1994)
 #' <doi:10.2307/2297912>.
 #'

R/misspecification_distance.R

@@ -0,0 +1,74 @@
+# Author: Alberto Quaini
+
+#############################################
+######  HJ misspecification distance ########
+#############################################
+
+
+#' @title Compute the HJ asset pricing model misspecification distance.
+#'
+#' @name HJMisspecificationDistance
+#' @description Computes the Kan-Robotti (2008) <10.1016/j.jempfin.2008.03.003>
+#' squared model misspecification distance:
+#' `square_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,
+#' and computes the associated confidence interval.
+#' 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.
+#' Clearly, computation of the confidence interval is obtained by means of an
+#' asymptotic analysis under potentially misspecified models, i.e.,
+#' without assuming correct model specification.
+#' Details can be found in Kan-Robotti (2008) <10.1016/j.jempfin.2008.03.003>.
+#'
+#' @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 ci_coverage A number indicating the confidence interval coverage
+#' probability. Default is `0.95`.
+#' @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` for internal check of all function
+#' arguments; `FALSE` otherwise. Default is `TRUE`.
+#'
+#' @return @return A list containing the squared misspecification-robust HJ
+#' distance in `squared_distance`, and the lower and upper confidence bounds
+#' in `lower_bound` and `upper_bound`, respectively.
+#'
+#' @examples
+#' # Import package data on 6 risk factors and 42 test asset excess returns
+#' factors = intrinsicFRP::factors[,-1]
+#' returns = intrinsicFRP::returns[,-1]
+#'
+#' # Compute the HJ model misspecification distance
+#' hj_test = HJMisspecificationDistance(returns, factors)
+#'
+#' @export
+HJMisspecificationDistance = function(
+  returns,
+  factors,
+  ci_coverage = 0.95,
+  hac_prewhite = FALSE,
+  check_arguments = TRUE
+) {
+
+  # Check the function arguments if check_arguments is TRUE
+  if (check_arguments) {
+
+    CheckData(returns, factors)
+    stopifnot("`ci_coverage` must be numeric" = is.numeric(ci_coverage))
+    stopifnot("`ci_coverage` must be between  0 and 1" = (ci_coverage >= 0.) & (ci_coverage <= 1.))
+    stopifnot("`hac_prewhite` must be boolean" = is.logical(hac_prewhite))
+
+  }
+
+  # Call the C++ implementation of the HJ Misspecification distance
+  return(.Call(`_intrinsicFRP_HJMisspecificationDistanceCpp`,
+    returns,
+    factors,
+    ci_coverage,
+    hac_prewhite
+  ))
+
+}

R/oracle_tfrp.R

@@ -7,7 +7,8 @@
 #' @title Oracle tradable factor risk premia.
 #'
 #' @name OracleTFRP
-#' @description Computes Oracle tradable factor risk premia from data on
+#' @description Computes Oracle tradable factor risk premia of
+#' Quaini-Trojani-Yuan (2023) <doi:10.2139/ssrn.4574683> from data on
 #' `K` factors `F = [F_1,...,F_K]'` and test asset excess returns `R`:
 #' `OTFRP = argmin_x ||TFRP - x||_2^2 + tau * sum_{k=1}^K w_k * |x_k|`,
 #' where `TFRP` is the tradable factor risk premia estimator, `tau > 0` is a

R/utils.R

@@ -71,7 +71,7 @@ CheckData = function(returns, factors) {
   stopifnot("`returns` and `factors` must have the same number of rows" = nrow(returns) == nrow(factors))
   stopifnot("`returns` contains more assets (columns) than observations (rows)" = nrow(returns) > ncol(returns))
   stopifnot("`factors` contains more variables (columns) than observations (rows)" = nrow(factors) > ncol(factors))
-  stopifnot("the number of `returns` must be grater than the number of `factors`" = ncol(returns) > ncol(factors))
+  stopifnot("the number of `returns` must be grater or equal to the number of `factors`" = ncol(returns) >= ncol(factors))
   stopifnot("`returns` must not contain missing values (NA/NaN)" = !anyNA(returns))
   stopifnot("`factors` must not contain missing values (NA/NaN)" = !anyNA(factors))