Nothing
#' Rolling Window Model
#'
#' Event study model with time-varying parameters estimated via a rolling
#' OLS window over the estimation period. The last rolling window's
#' parameters are used for event-window prediction. This captures parameter
#' instability that is common in financial return data.
#'
#' @family eventstudy-models
#' @export
RollingWindowModel <- R6Class("RollingWindowModel",
inherit = ModelBase,
public = list(
#' @field model_name Name of the model.
model_name = "RollingWindowModel",
#' @field window_size Rolling window size. Default 60.
window_size = 60L,
#' @field min_obs Minimum observations required. Default 30.
min_obs = 30L,
#' @description
#' Create a new RollingWindowModel.
#'
#' @param window_size Size of the rolling window.
#' @param min_obs Minimum valid (complete-pair) observations
#' required inside each individual rolling sub-window for that
#' sub-window to be fit. Distinct from \code{validate_task()}'s
#' \code{min_estimation_obs}, which is a whole-estimation-window
#' advisory threshold checked once per event, not per sub-window.
initialize = function(window_size = 60L, min_obs = 30L) {
self$window_size <- as.integer(window_size)
self$min_obs <- as.integer(min_obs)
},
#' @description
#' Fit the rolling window model on the estimation window.
#'
#' @param data_tbl Data frame or tibble with firm_returns,
#' index_returns, estimation_window, event_window columns.
fit = function(data_tbl) {
estimation_tbl <- data_tbl %>%
dplyr::filter(estimation_window == 1)
# Resolve degenerate mode once per fit call
mode <- .resolve_degenerate_mode(self$degenerate_mode)
# Guard 1: insufficient finite observations
# Use finite-pair count (not nrow) to catch NA-heavy windows
n_valid <- sum(!is.na(estimation_tbl$firm_returns) &
!is.na(estimation_tbl$index_returns))
if (n_valid < self$min_obs) {
.handle_degenerate(
mode = mode,
condition = paste0("insufficient estimation observations (",
n_valid, " valid, need ", self$min_obs, ")"),
component = self$model_name,
event_id = self$event_id,
firm_symbol = self$firm_symbol,
private_env = private
)
private$.is_fitted <- FALSE
return(invisible(self))
}
n_est <- nrow(estimation_tbl)
ws <- min(self$window_size, n_est)
# Guard 2: effective window size too small for OLS
if (ws < 3) {
.handle_degenerate(
mode = mode,
condition = paste0("effective window size (", ws,
") must be >= 3 for OLS with 2 parameters"),
component = self$model_name,
event_id = self$event_id,
firm_symbol = self$firm_symbol,
private_env = private
)
private$.is_fitted <- FALSE
return(invisible(self))
}
firm_ret <- estimation_tbl$firm_returns
idx_ret <- estimation_tbl$index_returns
# Rolling OLS: y = alpha + beta * x
n_windows <- n_est - ws + 1
alphas <- numeric(n_windows)
betas <- numeric(n_windows)
sigmas <- numeric(n_windows)
n_completes <- integer(n_windows)
for (i in seq_len(n_windows)) {
start <- i
end <- i + ws - 1
y_win <- firm_ret[start:end]
x_win <- idx_ret[start:end]
# A1 (2026-09-24): restrict to COMPLETE PAIRS only
# (both firm and index finite) before computing
# x_bar/y_bar/ss_xx/ss_xy/residuals/sigma. Computing
# x_bar/ss_xx from ALL x values -- including rows
# where y is NA -- silently biases beta whenever the
# NA-y rows are not missing-at-random in x (e.g. an
# index outlier co-occurring with a missing firm
# return). This matches what lm(firm ~ index) would
# do on the same window (na.omit of incomplete rows).
complete <- is.finite(y_win) & is.finite(x_win)
y <- y_win[complete]
x <- x_win[complete]
n_complete <- length(x)
n_completes[i] <- n_complete
if (n_complete >= 3) {
x_bar <- mean(x)
y_bar <- mean(y)
ss_xx <- sum((x - x_bar)^2)
ss_xy <- sum((x - x_bar) * (y - y_bar))
if (ss_xx > 0) {
betas[i] <- ss_xy / ss_xx
alphas[i] <- y_bar - betas[i] * x_bar
resid <- y - (alphas[i] + betas[i] * x)
# sigma denominator = n_complete_pairs - 2, matching
# summary(lm())$sigma on the same complete-pair window.
denom <- max(n_complete - 2, 1)
sigmas[i] <- sqrt(sum(resid^2) / denom)
} else {
betas[i] <- NA_real_
alphas[i] <- y_bar
sigmas[i] <- stats::sd(y)
}
} else {
betas[i] <- NA_real_
alphas[i] <- NA_real_
sigmas[i] <- NA_real_
}
}
private$.rolling_params <- list(
alphas = alphas, betas = betas, sigmas = sigmas,
n_completes = n_completes, ws = ws
)
alpha_last <- utils::tail(alphas, 1)
beta_last <- utils::tail(betas, 1)
# Guard 3: last-window parameters NA (e.g. zero-variance window)
if (is.na(alpha_last) || is.na(beta_last)) {
.handle_degenerate(
mode = mode,
condition = "last window parameters are NA; model cannot produce valid predictions",
component = self$model_name,
event_id = self$event_id,
firm_symbol = self$firm_symbol,
private_env = private
)
private$.is_fitted <- FALSE
return(invisible(self))
}
private$.is_fitted <- TRUE
private$calculate_statistics(data_tbl)
},
#' @description
#' Calculate abnormal returns using the last rolling window parameters.
#'
#' @param data_tbl Data frame or tibble.
abnormal_returns = function(data_tbl) {
if (private$.is_fitted) {
alpha_last <- utils::tail(private$.rolling_params$alphas, 1)
beta_last <- utils::tail(private$.rolling_params$betas, 1)
data_tbl %>%
dplyr::mutate(
abnormal_returns = firm_returns -
(alpha_last + beta_last * index_returns)
)
} else if (private$.degenerate_handled) {
# fit() already emitted one contract-formatted warning;
# return NA silently to honour the one-warning guarantee.
data_tbl %>%
dplyr::mutate(abnormal_returns = NA_real_)
} else {
warning(self$model_name, " is not fitted. Returning NA abnormal returns.")
data_tbl %>%
dplyr::mutate(abnormal_returns = NA_real_)
}
}
),
private = list(
.rolling_params = NULL,
calculate_statistics = function(data_tbl) {
alphas <- private$.rolling_params$alphas
betas <- private$.rolling_params$betas
sigmas <- private$.rolling_params$sigmas
alpha_last <- utils::tail(alphas, 1)
beta_last <- utils::tail(betas, 1)
sigma_last <- utils::tail(sigmas, 1)
private$.statistics$alpha <- alpha_last
private$.statistics$beta <- beta_last
private$.statistics$sigma <- sigma_last
# A6 (2026-09-24): RollingWindowModel always estimates
# 2 parameters (alpha, beta) via OLS.
private$.statistics$n_params <- 2
# A1 (2026-09-24): use the SAME complete-pair count that
# produced the LAST window's alpha/beta/sigma in fit() --
# not a freshly recomputed n_valid_est/ws, which could
# disagree with the actual last-window row span (fit()'s
# window is a fixed ROW span of estimation_tbl, not a
# valid-count span) and silently mismatch the df used for
# the reported sigma.
estimation_tbl <- data_tbl %>%
dplyr::filter(estimation_window == 1)
ws <- private$.rolling_params$ws
n_complete_last <- utils::tail(private$.rolling_params$n_completes, 1)
private$.statistics$degree_of_freedom <- max(n_complete_last - 2L, 1L)
last_window_full <- utils::tail(estimation_tbl, ws)
complete <- is.finite(last_window_full$firm_returns) &
is.finite(last_window_full$index_returns)
last_window <- last_window_full[complete, ]
residuals <- last_window$firm_returns -
(alpha_last + beta_last * last_window$index_returns)
private$add_residuals(residuals)
if (length(stats::na.omit(residuals)) >= 2) {
private$first_order_autocorrelation(residuals)
}
# Forecast error correction (complete-pair last window)
event_window_tbl <- data_tbl %>%
dplyr::filter(event_window == 1)
private$calculate_forecast_error_correction(
sigma_last, n_complete_last,
last_window$index_returns,
event_window_tbl$index_returns
)
# Store rolling time series for diagnostics
private$.statistics$rolling_alphas <- alphas
private$.statistics$rolling_betas <- betas
private$.statistics$rolling_sigmas <- sigmas
}
)
)
#' DCC-GARCH Model
#'
#' Event study model using Dynamic Conditional Correlation GARCH for
#' time-varying beta estimation. Requires the \pkg{rmgarch} package.
#' The bivariate DCC-GARCH model captures both time-varying volatility
#' and time-varying correlation between firm and market returns, yielding
#' a time-varying beta: \eqn{\beta_t = Cov(R_{firm}, R_{market})_t / Var(R_{market})_t}.
#'
#' @family eventstudy-models
#' @export
DCCGARCHModel <- R6Class("DCCGARCHModel",
inherit = ModelBase,
public = list(
#' @field model_name Name of the model.
model_name = "DCCGARCHModel",
#' @field garch_order GARCH order for each univariate model. Default c(1,1).
garch_order = c(1, 1),
#' @field dcc_order DCC order. Default c(1,1).
dcc_order = c(1, 1),
#' @description
#' Create a new DCCGARCHModel.
#'
#' @param garch_order GARCH(p,q) order for univariate models.
#' @param dcc_order DCC(a,b) order.
initialize = function(garch_order = c(1, 1),
dcc_order = c(1, 1)) {
self$garch_order <- garch_order
self$dcc_order <- dcc_order
},
#' @description
#' Fit the DCC-GARCH model on the estimation window.
#'
#' @param data_tbl Data frame or tibble with firm_returns,
#' index_returns, estimation_window, event_window columns.
fit = function(data_tbl) {
if (!requireNamespace("rmgarch", quietly = TRUE)) {
stop("Package 'rmgarch' is required for DCCGARCHModel. ",
"Install it with: install.packages('rmgarch')")
}
if (!requireNamespace("rugarch", quietly = TRUE)) {
stop("Package 'rugarch' is required for DCCGARCHModel. ",
"Install it with: install.packages('rugarch')")
}
estimation_tbl <- data_tbl %>%
dplyr::filter(estimation_window == 1)
# --- PRE-CALL contract guards (Phase 2) ---
# Inserted BEFORE returns_mat <- cbind(...).
# The existing purrr::safely(dccfit) / rcov / warning
# failure-handling below is Phase 3 and left untouched.
# Resolve degenerate mode once per fit call
mode <- .resolve_degenerate_mode(self$degenerate_mode)
# Guard 1: insufficient finite (firm, index) pairs
n_valid <- sum(!is.na(estimation_tbl$firm_returns) &
!is.na(estimation_tbl$index_returns))
if (n_valid < 2) {
.handle_degenerate(
mode = mode,
condition = paste0("insufficient estimation observations (",
n_valid, " valid, need 2)"),
component = self$model_name,
event_id = self$event_id,
firm_symbol = self$firm_symbol,
private_env = private
)
private$.is_fitted <- FALSE
return(invisible(self))
}
# Guard 2: zero or near-zero variance in either series
# DCC-GARCH requires BOTH series to have variance; zero variance
# in either series makes the univariate GARCH sub-model degenerate.
sd_firm <- stats::sd(estimation_tbl$firm_returns, na.rm = TRUE)
sd_index <- stats::sd(estimation_tbl$index_returns, na.rm = TRUE)
if (sd_firm < .Machine$double.eps) {
.handle_degenerate(
mode = mode,
condition = "zero or near-zero variance in firm_returns",
component = self$model_name,
event_id = self$event_id,
firm_symbol = self$firm_symbol,
private_env = private
)
private$.is_fitted <- FALSE
return(invisible(self))
}
if (sd_index < .Machine$double.eps) {
.handle_degenerate(
mode = mode,
condition = "zero or near-zero variance in index_returns",
component = self$model_name,
event_id = self$event_id,
firm_symbol = self$firm_symbol,
private_env = private
)
private$.is_fitted <- FALSE
return(invisible(self))
}
# --- end PRE-CALL guards ---
returns_mat <- cbind(estimation_tbl$firm_returns,
estimation_tbl$index_returns)
# Univariate GARCH specs
uspec <- rugarch::ugarchspec(
variance.model = list(model = "sGARCH",
garchOrder = self$garch_order),
mean.model = list(armaOrder = c(0, 0),
include.mean = TRUE),
distribution.model = "norm"
)
multi_uspec <- rugarch::multispec(
replicate(2, uspec)
)
# DCC spec
dcc_spec <- rmgarch::dccspec(
uspec = multi_uspec,
dccOrder = self$dcc_order,
distribution = "mvnorm"
)
safe_fit <- purrr::safely(rmgarch::dccfit)
res <- safe_fit(dcc_spec, data = returns_mat)
if (is.null(res$error)) {
# Check convergence of underlying GARCH fits.
# rmgarch does not expose a single convergence flag; we probe
# the conditional covariance matrices via rcov. Distinguish two
# outcomes so failures route to the correct handler:
# - rcov ERRORS -> statistics-extraction failure
# - rcov returns non-finite -> genuine non-convergence
conv_probe <- tryCatch(
list(ok = all(is.finite(rmgarch::rcov(res$result))),
err = NULL),
error = function(e) list(ok = NA, err = e)
)
if (!is.null(conv_probe$err)) {
# rcov (or covariance extraction) failed -> treat as a
# calculate_statistics failure so the message + one-warning
# contract match the statistics-failure path below.
private$.is_fitted <- FALSE
private$.degenerate_handled <- TRUE # suppress second warning in abnormal_returns()
warning("DCC-GARCH model statistics computation failed: ",
conditionMessage(conv_probe$err),
". Returning NA abnormal returns.", call. = FALSE)
} else if (isTRUE(conv_probe$ok)) {
private$.fitted_model <- res$result
private$.is_fitted <- TRUE
tryCatch(
private$calculate_statistics(data_tbl),
error = function(e) {
private$.is_fitted <- FALSE
private$.degenerate_handled <- TRUE # suppress second warning in abnormal_returns()
warning("DCC-GARCH model statistics computation failed: ",
conditionMessage(e),
". Returning NA abnormal returns.", call. = FALSE)
}
)
} else {
private$.is_fitted <- FALSE
private$.degenerate_handled <- TRUE # suppress second warning in abnormal_returns()
warning("DCC-GARCH model produced non-finite covariance. Returning NA.")
}
} else {
private$.is_fitted <- FALSE
private$.degenerate_handled <- TRUE # suppress second warning in abnormal_returns()
private$.error <- res$error
warning("DCC-GARCH fitting failed: ",
conditionMessage(res$error))
}
},
#' @description
#' Calculate abnormal returns using the last conditional beta.
#'
#' @param data_tbl Data frame or tibble.
abnormal_returns = function(data_tbl) {
if (private$.is_fitted) {
alpha_last <- private$.statistics$alpha
beta_last <- private$.statistics$beta
data_tbl %>%
dplyr::mutate(
abnormal_returns = firm_returns -
(alpha_last + beta_last * index_returns)
)
} else if (private$.degenerate_handled) {
# fit() already emitted one contract-formatted warning;
# return NA silently to honour the one-warning guarantee.
data_tbl %>%
dplyr::mutate(abnormal_returns = NA_real_)
} else {
warning(self$model_name, " is not fitted. Returning NA abnormal returns.")
data_tbl %>%
dplyr::mutate(abnormal_returns = NA_real_)
}
}
),
private = list(
calculate_statistics = function(data_tbl) {
dcc_fit <- private$.fitted_model
# Extract conditional covariance matrices
# rcov returns an array: [2, 2, T]
H <- rmgarch::rcov(dcc_fit)
n_t <- dim(H)[3]
# Time-varying beta: Cov(firm, market) / Var(market)
beta_t <- numeric(n_t)
for (t in seq_len(n_t)) {
mkt_var <- H[2, 2, t]
if (is.finite(mkt_var) && mkt_var > .Machine$double.eps) {
beta_t[t] <- H[1, 2, t] / mkt_var
} else {
beta_t[t] <- NA_real_
}
}
# Use last non-NA beta for prediction
beta_last <- beta_t[n_t]
if (is.na(beta_last)) {
non_na <- which(!is.na(beta_t))
beta_last <- if (length(non_na) > 0) beta_t[non_na[length(non_na)]] else 0
}
# Extract conditional sigma for firm
sigma_t <- sqrt(H[1, 1, ])
sigma_last <- sigma_t[n_t]
# Mean equation intercept
estimation_tbl <- data_tbl %>%
dplyr::filter(estimation_window == 1)
alpha_last <- mean(estimation_tbl$firm_returns -
beta_last * estimation_tbl$index_returns,
na.rm = TRUE)
private$.statistics$alpha <- alpha_last
private$.statistics$beta <- beta_last
private$.statistics$sigma <- mean(sigma_t, na.rm = TRUE)
private$.statistics$degree_of_freedom <- max(n_t - 4, 1)
# A6 (2026-09-24): the mean equation is alpha + beta * index
# (2 parameters); the DCC-GARCH variance/correlation
# parameters are not counted here (see GARCHModel).
private$.statistics$n_params <- 2
private$.statistics$beta_t <- beta_t
private$.statistics$sigma_t <- sigma_t
# Residuals from estimation window
residuals <- estimation_tbl$firm_returns -
(alpha_last + beta_last * estimation_tbl$index_returns)
private$add_residuals(residuals)
if (length(residuals) >= 2) {
private$first_order_autocorrelation(residuals)
}
# Forecast error correction
# Use n_valid (finite obs) not nrow \u2014 MODELS-04 FEC fix
event_window_tbl <- data_tbl %>%
dplyr::filter(event_window == 1)
n_valid_fec <- sum(!is.na(estimation_tbl$firm_returns) &
!is.na(estimation_tbl$index_returns))
private$calculate_forecast_error_correction(
mean(sigma_t, na.rm = TRUE),
n_valid_fec,
estimation_tbl$index_returns,
event_window_tbl$index_returns
)
}
)
)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.