| 1 |
|
| 2 |
#-------------------------------------------------- |
| 3 |
# confidence intervals for all model coefficients |
| 4 |
#--------------------------------------------------- |
| 5 |
|
| 6 |
#' Calculate confidence intervals for all or selected regression coefficients in |
| 7 |
#' a fitted model |
| 8 |
#' |
| 9 |
#' \code{conf_int} reports confidence intervals for each coefficient estimate in |
| 10 |
#' a fitted linear regression model, using a sandwich estimator for the standard |
| 11 |
#' errors and a small sample correction for the critical values. The |
| 12 |
#' small-sample correction is based on a Satterthwaite approximation. |
| 13 |
#' |
| 14 |
#' @param obj Fitted model for which to calculate confidence intervals. |
| 15 |
#' @param level Desired coverage level for confidence intervals. |
| 16 |
#' @param test Character vector specifying which small-sample corrections to |
| 17 |
#' calculate. \code{"z"} returns a z test (i.e., using a standard normal |
| 18 |
#' reference distribution). \code{"naive-t"} returns a t test with \code{m - |
| 19 |
#' 1} degrees of freedom, where \code{m} is the number of unique clusters. |
| 20 |
#' \code{"naive-tp"} returns a t test with \code{m - p} degrees of freedom, |
| 21 |
#' where \code{p} is the number of regression coefficients in \code{obj}. |
| 22 |
#' \code{"Satterthwaite"} returns a Satterthwaite correction. Unlike in |
| 23 |
#' \code{coef_test()}, \code{"saddlepoint"} is not currently supported in |
| 24 |
#' \code{conf_int()} because saddlepoint confidence intervals do not have a |
| 25 |
#' closed-form solution. |
| 26 |
#' |
| 27 |
#' @inheritParams coef_test |
| 28 |
#' |
| 29 |
#' @return A data frame containing estimated regression coefficients, standard |
| 30 |
#' errors, confidence intervals, and (optionally) p-values. |
| 31 |
#' |
| 32 |
#' @seealso \code{\link{vcovCR}} |
| 33 |
#' |
| 34 |
#' @examples |
| 35 |
#' |
| 36 |
#' data("ChickWeight", package = "datasets") |
| 37 |
#' lm_fit <- lm(weight ~ Diet * Time, data = ChickWeight) |
| 38 |
#' diet_index <- grepl("Diet.:Time", names(coef(lm_fit))) |
| 39 |
#' conf_int(lm_fit, vcov = "CR2", cluster = ChickWeight$Chick, coefs = diet_index) |
| 40 |
#' |
| 41 |
#' V_CR2 <- vcovCR(lm_fit, cluster = ChickWeight$Chick, type = "CR2") |
| 42 |
#' conf_int(lm_fit, vcov = V_CR2, level = .99, coefs = diet_index) |
| 43 |
#' |
| 44 |
#' @export |
| 45 |
|
| 46 |
conf_int <- function(obj, vcov, level = .95, test = "Satterthwaite", coefs = "All", ..., p_values = FALSE) { |
| 47 |
|
| 48 |
if (level <= 0 | level >= 1) stop("Confidence level must be between 0 and 1.") |
| 49 |
|
| 50 |
beta_full <- coef_CS(obj) |
| 51 |
beta_NA <- is.na(beta_full) |
| 52 |
p <- sum(!beta_NA) |
| 53 |
|
| 54 |
which_beta <- get_which_coef(beta_full, coefs) |
| 55 |
|
| 56 |
beta <- beta_full[which_beta & !beta_NA] |
| 57 |
|
| 58 |
if (is.character(vcov)) vcov <- vcovCR(obj, type = vcov, ...) |
| 59 |
if (!inherits(vcov, "clubSandwich")) stop("Variance-covariance matrix must be a clubSandwich.") |
| 60 |
|
| 61 |
all_tests <- c("z","naive-t","naive-tp","Satterthwaite") |
| 62 |
if (test == "saddlepoint") stop("test = 'saddlepoint' is not currently supported because saddlepoint confidence intervals do not have a closed-form solution.") |
| 63 |
test <- match.arg(test, all_tests, several.ok = FALSE) |
| 64 |
|
| 65 |
SE <- sqrt(diag(vcov))[which_beta[!beta_NA]] |
| 66 |
|
| 67 |
if (test=="Satterthwaite") { |
| 68 |
P_array <- get_P_array(get_GH(obj, vcov))[,,which_beta[!beta_NA],drop=FALSE] |
| 69 |
} |
| 70 |
|
| 71 |
df <- switch(test, |
| 72 |
z = Inf, |
| 73 |
`naive-t` = nlevels(attr(vcov, "cluster")) - 1, |
| 74 |
`naive-tp` = nlevels(attr(vcov, "cluster")) - p, |
| 75 |
`Satterthwaite` = Satterthwaite_df(P_array = P_array) |
| 76 |
) |
| 77 |
|
| 78 |
crit <- qt(1 - (1 - level) / 2, df = df) |
| 79 |
|
| 80 |
result <- data.frame( |
| 81 |
Coef = names(beta), |
| 82 |
beta = beta, |
| 83 |
SE = SE, |
| 84 |
df = df, |
| 85 |
CI_L = beta - SE * crit, |
| 86 |
CI_U = beta + SE * crit |
| 87 |
) |
| 88 |
row.names(result) <- result$Coef |
| 89 |
|
| 90 |
if (p_values) { |
| 91 |
t_stat <- result$beta / result$SE |
| 92 |
result$p_val <- 2 * pt(abs(t_stat), df = result$df, lower.tail = FALSE) |
| 93 |
} |
| 94 |
|
| 95 |
class(result) <- c("conf_int_clubSandwich", class(result)) |
| 96 |
attr(result, "type") <- attr(vcov, "type") |
| 97 |
attr(result, "level") <- level |
| 98 |
|
| 99 |
result |
| 100 |
} |
| 101 |
|
| 102 |
#-------------------------------------------------- |
| 103 |
# confidence intervals for linear contrasts |
| 104 |
#--------------------------------------------------- |
| 105 |
|
| 106 |
#' Calculate confidence intervals and p-values for linear contrasts of |
| 107 |
#' regression coefficients in a fitted model |
| 108 |
#' |
| 109 |
#' \code{linear_contrast} reports confidence intervals and (optionally) p-values |
| 110 |
#' for linear contrasts of regression coefficients from a fitted model, using a |
| 111 |
#' sandwich estimator for the standard errors and (optionally) a small sample |
| 112 |
#' correction for the critical values. The default small-sample correction is |
| 113 |
#' based on a Satterthwaite approximation. |
| 114 |
#' |
| 115 |
#' @param obj Fitted model for which to calculate confidence intervals. |
| 116 |
#' @param contrasts A contrast matrix, or a list of multiple contrast matrices |
| 117 |
#' to test. See details and examples. |
| 118 |
#' @param level Desired coverage level for confidence intervals. |
| 119 |
#' @param test Character vector specifying which small-sample corrections to |
| 120 |
#' calculate. \code{"z"} returns a z test (i.e., using a standard normal |
| 121 |
#' reference distribution). \code{"naive-t"} returns a t test with \code{m - |
| 122 |
#' 1} degrees of freedom, where \code{m} is the number of unique clusters. |
| 123 |
#' \code{"naive-tp"} returns a t test with \code{m - p} degrees of freedom, |
| 124 |
#' where \code{p} is the number of regression coefficients in \code{obj}. |
| 125 |
#' \code{"Satterthwaite"} returns a Satterthwaite correction. Unlike in |
| 126 |
#' \code{coef_test()}, \code{"saddlepoint"} is not currently supported in |
| 127 |
#' \code{conf_int()} because saddlepoint confidence intervals do not have a |
| 128 |
#' closed-form solution. |
| 129 |
#' @param p_values Logical indicating whether to report p-values. The default |
| 130 |
#' value is \code{FALSE}. |
| 131 |
#' @param adjustment_method Correction method, a \code{\link{character}} string |
| 132 |
#' from \code{p.adjust.methods}, which is passed to \code{\link{p.adjust}} to |
| 133 |
#' correct p-values in the case of multiple comparisons. Defaults to |
| 134 |
#' \code{"none"}. Any value given will be ignored if \code{p_values = FALSE}. |
| 135 |
#' @inheritParams coef_test |
| 136 |
#' |
| 137 |
#' @details Constraints can be specified directly as q X p matrices or |
| 138 |
#' indirectly through \code{\link{constrain_pairwise}}, |
| 139 |
#' \code{\link{constrain_equal}}, or \code{\link{constrain_zero}}. |
| 140 |
#' |
| 141 |
#' @return A data frame containing estimated contrasts, standard |
| 142 |
#' errors, confidence intervals, and (optionally) p-values. |
| 143 |
#' |
| 144 |
#' @seealso \code{\link{vcovCR}} |
| 145 |
#' |
| 146 |
#' @examples |
| 147 |
#' |
| 148 |
#' data("ChickWeight", package = "datasets") |
| 149 |
#' lm_fit <- lm(weight ~ 0 + Diet + Time:Diet, data = ChickWeight) |
| 150 |
#' |
| 151 |
#' # Pairwise comparisons of diet-by-time slopes |
| 152 |
#' linear_contrast(lm_fit, vcov = "CR2", cluster = ChickWeight$Chick, |
| 153 |
#' contrasts = constrain_pairwise("Diet.:Time", reg_ex = TRUE)) |
| 154 |
#' |
| 155 |
#' |
| 156 |
#' if (requireNamespace("carData", quietly = TRUE)) withAutoprint({ |
| 157 |
#' |
| 158 |
#' data(Duncan, package = "carData") |
| 159 |
#' Duncan$cluster <- sample(LETTERS[1:8], size = nrow(Duncan), replace = TRUE) |
| 160 |
#' |
| 161 |
#' Duncan_fit <- lm(prestige ~ 0 + type + income + type:income + type:education, data=Duncan) |
| 162 |
#' # Note that type:income terms are interactions because main effect of income is included |
| 163 |
#' # but type:education terms are separate slopes for each unique level of type |
| 164 |
#' |
| 165 |
#' # Pairwise comparisons of type-by-education slopes |
| 166 |
#' linear_contrast(Duncan_fit, vcov = "CR2", cluster = Duncan$cluster, |
| 167 |
#' contrasts = constrain_pairwise(":education", reg_ex = TRUE), |
| 168 |
#' test = "Satterthwaite") |
| 169 |
#' |
| 170 |
#' # Repeat the above, but with p-values displayed and multiple comparisons adjustment applied. |
| 171 |
#' linear_contrast(Duncan_fit, vcov = "CR2", cluster = Duncan$cluster, |
| 172 |
#' contrasts = constrain_pairwise(":education", reg_ex = TRUE), |
| 173 |
#' test = "Satterthwaite", p_values = TRUE, adjustment_method = "hochberg") |
| 174 |
#' |
| 175 |
#' # Pairwise comparisons of type-by-income interactions |
| 176 |
#' linear_contrast(Duncan_fit, vcov = "CR2", cluster = Duncan$cluster, |
| 177 |
#' contrasts = constrain_pairwise(":income", reg_ex = TRUE, with_zero = TRUE), |
| 178 |
#' test = "Satterthwaite") |
| 179 |
#' |
| 180 |
#' }) |
| 181 |
#' |
| 182 |
#' @export |
| 183 |
|
| 184 |
linear_contrast <- function(obj, vcov, contrasts, level = .95, test = "Satterthwaite", ..., p_values = FALSE, adjustment_method = "none") { |
| 185 |
|
| 186 |
if (level <= 0 | level >= 1) stop("Confidence level must be between 0 and 1.") |
| 187 |
|
| 188 |
beta_full <- coef_CS(obj) |
| 189 |
beta_NA <- is.na(beta_full) |
| 190 |
p <- sum(!beta_NA) |
| 191 |
beta <- beta_full[!beta_NA] |
| 192 |
|
| 193 |
if (is.character(vcov)) vcov <- vcovCR(obj, type = vcov, ...) |
| 194 |
if (!inherits(vcov, "clubSandwich")) stop("Variance-covariance matrix must be a clubSandwich.") |
| 195 |
|
| 196 |
# Evaluate constrain_*() functions if used |
| 197 |
if (inherits(contrasts, "function")) { |
| 198 |
contrasts <- contrasts(beta_full) |
| 199 |
} |
| 200 |
|
| 201 |
if (is.list(contrasts)) { |
| 202 |
|
| 203 |
contrast_list <- lapply(contrasts, function(x) { |
| 204 |
if (inherits(x, "function")) x(beta_full) else x |
| 205 |
}) |
| 206 |
|
| 207 |
if (any(sapply(contrast_list, is.list))) { |
| 208 |
contrast_list <- lapply(contrast_list, function(x) if (is.list(x)) x else list(x)) |
| 209 |
contrast_list <- do.call(c, args = contrast_list) |
| 210 |
} |
| 211 |
|
| 212 |
# List of contrasts |
| 213 |
if (!all(sapply(contrast_list, inherits, "matrix") & sapply(contrast_list, ncol) == p)) { |
| 214 |
stop(paste0("Contrasts must be a q X ", p," matrix, a list of such matrices, or a call to a constrain_*() function.")) |
| 215 |
} |
| 216 |
|
| 217 |
# Add row names to contrasts |
| 218 |
contrast_list <- mapply(function(x,r) { |
| 219 |
if (is.null(rownames(x))) { |
| 220 |
if (nrow(x) > 1) { |
| 221 |
rownames(x) <- paste(r, 1:nrow(x), sep = ".") |
| 222 |
} else { |
| 223 |
rownames(x) <- r |
| 224 |
} |
| 225 |
} else { |
| 226 |
rownames(x) <- paste(r, rownames(x), sep = ".") |
| 227 |
} |
| 228 |
return(x) |
| 229 |
}, |
| 230 |
x = contrast_list, r = names(contrast_list), |
| 231 |
SIMPLIFY = FALSE) |
| 232 |
|
| 233 |
# Combine into one matrix |
| 234 |
contrasts <- do.call(rbind, args = contrast_list) |
| 235 |
} else if (is.matrix(contrasts)) { |
| 236 |
if (is.null(rownames(contrasts))) { |
| 237 |
rownames(contrasts) <- paste("Contrast", 1:NROW(contrasts)) |
| 238 |
} |
| 239 |
} else if (is.vector(contrasts)) { |
| 240 |
contrasts <- matrix(contrasts, nrow = 1L) |
| 241 |
rownames(contrasts) <- "Contrast" |
| 242 |
} |
| 243 |
|
| 244 |
all_tests <- c("z","naive-t","naive-tp","Satterthwaite") |
| 245 |
if (test == "saddlepoint") stop("test = 'saddlepoint' is not currently supported because saddlepoint confidence intervals do not have a closed-form solution.") |
| 246 |
test <- match.arg(test, all_tests, several.ok = FALSE) |
| 247 |
|
| 248 |
# Calculate contrasts |
| 249 |
est <- contrasts %*% beta |
| 250 |
|
| 251 |
# Standard error of the contrasts |
| 252 |
vcov_contrasts <- contrasts %*% vcov %*% t(contrasts) |
| 253 |
SE <- sqrt(diag(vcov_contrasts)) |
| 254 |
|
| 255 |
# Satterthwaite degrees of freedom |
| 256 |
if (test=="Satterthwaite") { |
| 257 |
q <- nrow(contrasts) |
| 258 |
GH <- get_GH(obj, vcov) |
| 259 |
GH$G <- lapply(GH$G, function(s) contrasts %*% s) |
| 260 |
dims <- dim(GH$H) |
| 261 |
if (length(dims)==3) { |
| 262 |
GH$H <- array_multiply(contrasts, GH$H) |
| 263 |
} else { |
| 264 |
H <- array(NA, dim = c(3, q, dims[3:4])) |
| 265 |
for (i in 1:dims[1]) { |
| 266 |
Hi <- GH$H[i,,,] |
| 267 |
dim(Hi) <- dims[-1L] |
| 268 |
H[i,,,] <- array_multiply(contrasts, Hi) |
| 269 |
} |
| 270 |
GH$H <- H |
| 271 |
} |
| 272 |
P_array <- get_P_array(GH = GH) |
| 273 |
} |
| 274 |
|
| 275 |
df <- switch(test, |
| 276 |
z = Inf, |
| 277 |
`naive-t` = nlevels(attr(vcov, "cluster")) - 1, |
| 278 |
`naive-tp` = nlevels(attr(vcov, "cluster")) - p, |
| 279 |
`Satterthwaite` = Satterthwaite_df(P_array = P_array) |
| 280 |
) |
| 281 |
|
| 282 |
crit <- qt(1 - (1 - level) / 2, df = df) |
| 283 |
|
| 284 |
result <- data.frame( |
| 285 |
Coef = rownames(contrasts), |
| 286 |
Est = est, |
| 287 |
SE = SE, |
| 288 |
df = df, |
| 289 |
CI_L = est - SE * crit, |
| 290 |
CI_U = est + SE * crit |
| 291 |
) |
| 292 |
row.names(result) <- result$Coef |
| 293 |
|
| 294 |
# p-value adjustment method |
| 295 |
adjustment_method <- match.arg(adjustment_method, p.adjust.methods, several.ok = FALSE) |
| 296 |
|
| 297 |
if (p_values) { |
| 298 |
t_stat <- result$Est / result$SE |
| 299 |
result$p_val <- 2 * pt(abs(t_stat), df = result$df, lower.tail = FALSE) |
| 300 |
|
| 301 |
# p-value adjustment |
| 302 |
if (adjustment_method != "none" & nrow(result) == 1) { |
| 303 |
warning("Only one p-value is available. No p-value adjustment will be performed.") # warning by copilot |
| 304 |
} else if (adjustment_method != "none") { |
| 305 |
result$p_val <- p.adjust(result$p_val, method = adjustment_method) |
| 306 |
} |
| 307 |
|
| 308 |
} else if (adjustment_method != "none") { |
| 309 |
warning("p_values = FALSE, so p-value adjustment is not applied.") # warning by copilot |
| 310 |
} |
| 311 |
|
| 312 |
class(result) <- c("conf_int_clubSandwich", class(result)) |
| 313 |
attr(result, "type") <- attr(vcov, "type") |
| 314 |
attr(result, "level") <- level |
| 315 |
|
| 316 |
result |
| 317 |
} |
| 318 |
|
| 319 |
#--------------------------------------------- |
| 320 |
# print method for conf_int |
| 321 |
#--------------------------------------------- |
| 322 |
|
| 323 |
#' @export |
| 324 |
|
| 325 |
print.conf_int_clubSandwich <- function(x, digits = 3, ...) { |
| 326 |
lev <- paste0(100 * attr(x, "level"), "%") |
| 327 |
res_names <- c("Coef.", "Estimate", "SE", "d.f.", paste(c("Lower", "Upper"), lev, "CI")) |
| 328 |
if ("p_val" %in% names(x)) { |
| 329 |
x$Sig <- cut(x$p_val, breaks = c(0, 0.001, 0.01, 0.05, 0.1, 1), |
| 330 |
labels = c("***", "**", "*", ".", " "), include.lowest = TRUE) |
| 331 |
x$p_val <- format.pval(x$p_val, digits = digits, eps = 10^-digits) |
| 332 |
res_names <- c(res_names, "p-value", "Sig.") |
| 333 |
} |
| 334 |
names(x) <- res_names |
| 335 |
print(format(x, digits = 3), row.names = FALSE) |
| 336 |
} |