Add vignette on custom contrasts and joint tests (#502)

* Add vignette on custom contrasts and joint tests

* draft

* finalize draft

* fiix

* typos

* styler

* fix

* fix

* add test

* fix

* fix

* news, desc

Author: strengejacke

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: modelbased
 Title: Estimation of Model-Based Predictions, Contrasts and Means
-Version: 0.11.0.4
+Version: 0.11.0.5
 Authors@R:
     c(person(given = "Dominique",
              family = "Makowski",

NEWS.md

@@ -8,6 +8,9 @@
 * The `comparison` argument can now also be `"joint"`, to jointly test
   hypotheses (i.e. conducting a joint test) in factorial designs.
 
+* New vignette about user-defined contrasts and joint tests in
+  `estimate_contrasts()`.
+
 # modelbased 0.11.0
 
 ## New functions

R/estimate_grouplevel.R

@@ -223,10 +223,12 @@ estimate_grouplevel.stanreg <- function(model,
   if (!is.null(clean_parameters)) {
     # fix for rstanarm, which contains a sigma columns
     clean_parameters <- clean_parameters[
-      clean_parameters$Component != "sigma" & !startsWith(clean_parameters$Parameter, "Sigma["), , drop = FALSE # nolint
+      clean_parameters$Component != "sigma" & !startsWith(clean_parameters$Parameter, "Sigma["), ,
+      drop = FALSE # nolint
     ]
     clean_parameters <- clean_parameters[
-      clean_parameters$Parameter %in% params$Parameter, , drop = FALSE
+      clean_parameters$Parameter %in% params$Parameter, ,
+      drop = FALSE
     ]
 
     params$Parameter <- insight::trim_ws(sub(":.*", "", clean_parameters$Group))

R/format.R

@@ -6,6 +6,11 @@ format.estimate_contrasts <- function(x,
                                       select = getOption("modelbased_select", NULL),
                                       include_grid = getOption("modelbased_include_grid", FALSE),
                                       ...) {
+  # for joint test, no select and include_grid options
+  if (isTRUE(attributes(x)$joint_test)) {
+    select <- NULL
+    include_grid <- FALSE
+  }
   # don't print columns of adjusted_for variables
   adjusted_for <- attr(x, "adjusted_for", exact = TRUE)
   if (!is.null(adjusted_for) && all(adjusted_for %in% colnames(x)) && !isTRUE(include_grid)) {

pkgdown/_pkgdown.yml

@@ -84,12 +84,14 @@ navbar:
         - text: "Contrasts"
         - text: "Contrasts and comparisons"
           href: articles/introduction_comparisons_1.html
-        - text: "Slopes, floodlight and spotlight analysis (Johnson-Neyman intervals)"
+        - text: "User Defined Contrasts and Joint Tests"
           href: articles/introduction_comparisons_2.html
-        - text: "Contrasts and comparisons for generalized linear models"
+        - text: "Slopes, floodlight and spotlight analysis (Johnson-Neyman intervals)"
           href: articles/introduction_comparisons_3.html
-        - text: "Contrasts and comparisons for zero-inflation models"
+        - text: "Contrasts and comparisons for generalized linear models"
           href: articles/introduction_comparisons_4.html
+        - text: "Contrasts and comparisons for zero-inflation models"
+          href: articles/introduction_comparisons_5.html
     - icon: fa fa-newspaper
       text: News
       href: news/index.html

tests/testthat/_snaps/joint_test.md

@@ -0,0 +1,14 @@
+# estimate_contrasts - joint test, works with select printing
+
+    Code
+      estimate_contrasts(m, contrast = "time", by = "coffee", comparison = "joint")
+    Output
+      Marginal Joint Test
+      
+      Contrast | coffee  | df1 | df2 |    F |     p
+      ---------------------------------------------
+      time     | coffee  | 2   | 114 | 1.76 | 0.176
+      time     | control | 2   | 114 | 5.29 | 0.006
+      
+      p-values are uncorrected.
+

tests/testthat/test-joint_test.R

@@ -137,11 +137,23 @@ test_that("estimate_contrasts - joint test, 3-way", {
 })
 
 
-test_that("estimate_contrasts - joint test, 3-way", {
+test_that("estimate_contrasts - joint test, 3-way, error", {
   data(coffee_data, package = "modelbased")
   m <- lm(alertness ~ time * coffee * sex, data = coffee_data)
   expect_error(
     estimate_contrasts(m, contrast = "time", comparison = "joint"),
     regex = "Joint tests using"
   )
 })
+
+
+skip_if_not_installed("withr")
+
+withr::with_options(
+  list(modelbased_select = "minimal"),
+  test_that("estimate_contrasts - joint test, works with select printing", {
+    data(coffee_data, package = "modelbased")
+    m <- lm(alertness ~ time * coffee, data = coffee_data)
+    expect_snapshot(estimate_contrasts(m, contrast = "time", by = "coffee", comparison = "joint"))
+  })
+)

vignettes/estimate_slopes.Rmd

@@ -101,7 +101,7 @@ plot(slopes)
 
 Interactions between two continuous variables are often not straightforward to visualize and interpret. Thanks to the model-based approach, one can represent the effect of one of the variables as a function of the other variable.
 
-Such plot, also referred to as **Johnson-Neyman intervals**, shows how the effect (the "slope") of one variable varies depending on another variable. It is useful in the case of complex interactions between continuous variables. See also [this vignette](https://easystats.github.io/modelbased/articles/introduction_comparisons_2.html) for further details.
+Such plot, also referred to as **Johnson-Neyman intervals**, shows how the effect (the "slope") of one variable varies depending on another variable. It is useful in the case of complex interactions between continuous variables. See also [this vignette](https://easystats.github.io/modelbased/articles/introduction_comparisons_3.html) for further details.
 
 For instance, the plot below shows that the effect of `hp` (the y-axis) is significantly negative only when `wt` is low (`< ~4`).
 

vignettes/introduction_comparisons_1.Rmd

@@ -33,15 +33,17 @@ if (!all(insight::check_if_installed(pkgs, quietly = TRUE))) {
 ```
 
 
-This vignette is the first in a 4-part series:
+This vignette is the first in a 5-part series:
 
 1. **Contrasts and Pairwise Comparisons**
 
-2. [**Comparisons of Slopes, Floodlight and Spotlight Analysis (Johnson-Neyman Intervals)**](https://easystats.github.io/modelbased/articles/introduction_comparisons_2.html)
+2. [**User Defined Contrasts and Joint Tests**](https://easystats.github.io/modelbased/articles/introduction_comparisons_2.html)
 
-3. [**Contrasts and Comparisons for Generalized Linear Models**](https://easystats.github.io/modelbased/articles/introduction_comparisons_3.html)
+3. [**Comparisons of Slopes, Floodlight and Spotlight Analysis (Johnson-Neyman Intervals)**](https://easystats.github.io/modelbased/articles/introduction_comparisons_3.html)
 
-4. [**Contrasts and Comparisons for Zero-Inflation Models**](https://easystats.github.io/modelbased/articles/introduction_comparisons_4.html)
+4. [**Contrasts and Comparisons for Generalized Linear Models**](https://easystats.github.io/modelbased/articles/introduction_comparisons_4.html)
+
+5. [**Contrasts and Comparisons for Zero-Inflation Models**](https://easystats.github.io/modelbased/articles/introduction_comparisons_5.html)
 
 
 # Hypothesis testing for categorical predictors
@@ -316,4 +318,4 @@ Let's replicate this step-by-step:
 
 While the current implementation in `estimate_contrasts()` already covers many common use cases for testing contrasts and pairwise comparison, there still might be the need for more sophisticated comparisons. In this case, we recommend using the [*marginaleffects*](https://marginaleffects.com/) package directly. Some further related recommended readings are the vignettes about [Comparisons](https://marginaleffects.com/chapters/comparisons.html) or [Hypothesis Tests](https://marginaleffects.com/chapters/hypothesis.html).
 
-[Go to next vignette: **Comparisons of Slopes, Floodlight and Spotlight Analysis (Johnson-Neyman Intervals)**](https://easystats.github.io/modelbased/articles/introduction_comparisons_2.html)
+[Go to next vignette: **User Defined Contrasts and Joint Tests**](https://easystats.github.io/modelbased/articles/introduction_comparisons_2.html)