Debian Codegraph @

R/conf_int.R

raw
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 }