Add vcov option to docs and examples (#1014)

* Add `vcov` option to docs and examples

* news desc

* docs

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: parameters
 Title: Processing of Model Parameters
-Version: 0.22.2.8
+Version: 0.22.2.9
 Authors@R:
     c(person(given = "Daniel",
              family = "Lüdecke",

NEWS.md

@@ -12,6 +12,10 @@
 * `p_function()` gets a `vcov` and `vcov_args` argument to compute robust
   standard errors for the confidence curves.
 
+* Functions `p_significance()` and `equivalence_test()` now pass arguments
+  `vcov` and `vcov_args` to `p_value()` and `ci()`, hence, tests can be based
+  on robust standard errors.
+
 * Revision / enhancement of some documentation.
 
 # parameters 0.22.2

R/2_ci.R

@@ -24,13 +24,25 @@
 #' @param iterations The number of bootstrap replicates. Only applies to models
 #'   of class `merMod` when `method=boot`.
 #' @param verbose Toggle warnings and messages.
-#' @param ... Additional arguments
+#' @param ... Additional arguments passed down to the underlying functions.
+#' E.g., arguments like `vcov` or `vcov_args` can be used to compute confidence
+#' intervals using a specific variance-covariance matrix for the standard
+#' errors.
 #'
 #' @return A data frame containing the CI bounds.
 #'
 #' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom
 #'
-#' @examplesIf require("glmmTMB")
+#' @examplesIf require("glmmTMB") && requireNamespace("sandwich")
+#' data(qol_cancer)
+#' model <- lm(QoL ~ time + age + education, data = qol_cancer)
+#'
+#' # regular confidence intervals
+#' ci(model)
+#'
+#' # using heteroscedasticity-robust standard errors
+#' ci(model, vcov = "HC3")
+#'
 #' \donttest{
 #' library(parameters)
 #' data(Salamanders, package = "glmmTMB")

R/equivalence_test.R

@@ -19,7 +19,10 @@ bayestestR::equivalence_test
 #' See [`?ggeffects::test_predictions`](https://strengejacke.github.io/ggeffects/reference/test_predictions.html)
 #' for details.
 #' @param verbose Toggle warnings and messages.
-#' @param ... Arguments passed to or from other methods.
+#' @param ... Arguments passed to or from other methods, e.g. `ci()`. Arguments
+#' like `vcov` or `vcov_args` can be used to compute confidence intervals or
+#' p-values using a specific variance-covariance matrix for the standard
+#' errors..
 #' @inheritParams model_parameters.merMod
 #' @inheritParams p_value
 #'
@@ -218,13 +221,16 @@ bayestestR::equivalence_test
 #'     Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x}
 #'
 #' @return A data frame.
-#' @examples
+#' @examplesIf requireNamespace("sandwich")
 #' data(qol_cancer)
 #' model <- lm(QoL ~ time + age + education, data = qol_cancer)
 #'
 #' # default rule
 #' equivalence_test(model)
 #'
+#' # using heteroscedasticity-robust standard errors
+#' equivalence_test(model, vcov = "HC3")
+#'
 #' # conditional equivalence test
 #' equivalence_test(model, rule = "cet")
 #'
@@ -504,14 +510,14 @@ equivalence_test.ggeffects <- function(x,
 
   # ==== requested confidence intervals ====
 
-  params <- conf_int <- .ci_generic(x, ci = ci)
+  params <- conf_int <- .ci_generic(x, ci = ci, ...)
   conf_int <- as.data.frame(t(conf_int[, c("CI_low", "CI_high")]))
 
 
   # ==== the "narrower" intervals (1-2*alpha) for CET-rules. ====
 
   alpha <- 1 - ci
-  conf_int2 <- .ci_generic(x, ci = (ci - alpha))
+  conf_int2 <- .ci_generic(x, ci = (ci - alpha), ...)
   conf_int2 <- as.data.frame(t(conf_int2[, c("CI_low", "CI_high")]))
 
 
@@ -544,7 +550,7 @@ equivalence_test.ggeffects <- function(x,
 
   # ==== (adjusted) p-values for tests ====
 
-  out$p <- .add_p_to_equitest(x, ci, range)
+  out$p <- .add_p_to_equitest(x, ci, range, ...)
 
   attr(out, "rope") <- range
   out
@@ -786,7 +792,7 @@ equivalence_test.ggeffects <- function(x,
 }
 
 
-.add_p_to_equitest <- function(model, ci, range) {
+.add_p_to_equitest <- function(model, ci, range, ...) {
   tryCatch(
     {
       params <- insight::get_parameters(model)
@@ -798,7 +804,7 @@ equivalence_test.ggeffects <- function(x,
       params$mu <- params$Estimate * -1
 
       # se
-      se <- standard_error(model)
+      se <- standard_error(model, ...)
 
       stats::pt((range[1] - params$mu) / se$SE, df = dof, lower.tail = TRUE) +
         stats::pt((range[2] - params$mu) / se$SE, df = dof, lower.tail = FALSE)

R/p_direction.R

@@ -16,7 +16,9 @@ bayestestR::p_direction
 #' @param x A statistical model.
 #' @inheritParams bayestestR::p_direction
 #' @inheritParams model_parameters.default
-#' @param ... Arguments passed to other methods, e.g. `ci()`.
+#' @param ... Arguments passed to other methods, e.g. `ci()`. Arguments like
+#' `vcov` or `vcov_args` can be used to compute confidence intervals using a
+#' specific variance-covariance matrix for the standard errors.
 #'
 #' @seealso See also [`equivalence_test()`], [`p_function()`] and
 #' [`p_significance()`] for functions related to checking effect existence and
@@ -70,11 +72,14 @@ bayestestR::p_direction
 #'
 #' @return A data frame.
 #'
-#' @examplesIf requireNamespace("bayestestR") && require("see", quietly = TRUE)
+#' @examplesIf requireNamespace("bayestestR") && require("see", quietly = TRUE) && requireNamespace("sandwich")
 #' data(qol_cancer)
 #' model <- lm(QoL ~ time + age + education, data = qol_cancer)
 #' p_direction(model)
 #'
+#' # based on heteroscedasticity-robust standard errors
+#' p_direction(model, vcov = "HC3")
+#'
 #' result <- p_direction(model)
 #' plot(result)
 #' @export

R/p_function.R

@@ -119,9 +119,11 @@
 #' whereas values values far from the observed point estimate (where _p_
 #' approaches 0) are least compatible with the data and model assumptions
 #' (_Schweder and Hjort 2016, pp. 60-61; Amrhein and Greenland 2022_). In this
-#' regards, _p_-values are are statements about confidence/compatibility, not
-#' probability per se, but still the interpretation of _p_-values might be
-#' guided using [`bayestestR::p_to_pd()`]
+#' regards, _p_-values are statements about _confidence_ or _compatibility_ and
+#' can be considered as _epistemic probability_ - "not necessarily of the
+#' hypothesis being true, but of it _possibly_ being true" (_Schweder 2018_).
+#' Hence, the interpretation of _p_-values might be guided using
+#' [`bayestestR::p_to_pd()`]
 #'
 #' ## Compatibility intervals - is their interpretation conditional or not?
 #'

R/p_significance.R

@@ -28,7 +28,9 @@ bayestestR::p_significance
 #' @inheritParams bayestestR::p_significance
 #' @inheritParams model_parameters.default
 #' @param verbose Toggle warnings and messages.
-#' @param ... Arguments passed to other methods, e.g. `ci()`.
+#' @param ... Arguments passed to other methods, e.g. `ci()`. Arguments like
+#' `vcov` or `vcov_args` can be used to compute confidence intervals using a
+#' specific variance-covariance matrix for the standard errors.
 #'
 #' @seealso For more details, see [`bayestestR::p_significance()`]. See also
 #' [`equivalence_test()`], [`p_function()`] and [`bayestestR::p_direction()`]
@@ -126,14 +128,16 @@ bayestestR::p_significance
 #' intervals and the values for practical significance. Higher values indicate
 #' more practical significance (upper bound is one).
 #'
-#' @examplesIf requireNamespace("bayestestR") && packageVersion("bayestestR") > "0.14.0"
+#' @examplesIf requireNamespace("bayestestR") && packageVersion("bayestestR") > "0.14.0" && requireNamespace("sandwich")
 #' data(qol_cancer)
 #' model <- lm(QoL ~ time + age + education, data = qol_cancer)
 #'
 #' p_significance(model)
 #' p_significance(model, threshold = c(-0.5, 1.5))
 #'
-#' # plot method
+#' # based on heteroscedasticity-robust standard errors
+#' p_significance(model, vcov = "HC3")
+#'
 #' if (require("see", quietly = TRUE)) {
 #'   result <- p_significance(model)
 #'   plot(result)