Add comparison = "ratio" as shortcut

DESCRIPTION

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

NEWS.md

@@ -28,6 +28,9 @@
   now `predict = "prob"`, which returns the same probabilities as the
   `"marginaleffects"` backend.
 
+* `comparison = "ratio"` is a new shortcut to compute pairwise comparisons
+  as ratios.
+
 ## Bug fixes
 
 * Fixed issue in `estimate_contrasts()` with wrong assignment of estimates in

R/estimate_contrasts.R

@@ -42,7 +42,7 @@
 #'   described below, see documentation of [marginaleffects::comparisons],
 #'   [this website](https://marginaleffects.com/bonus/hypothesis.html) and
 #'   section _Comparison options_ below.
-#'   * String: One of `"pairwise"`, `"revpairwise"`, `"reference"`,
+#'   * String: One of `"pairwise"`, `"ratio"`, `"revpairwise"`, `"reference"`,
 #'     `"sequential"`, `"meandev"` `"meanotherdev"`, `"poly"`, `"helmert"`, or
 #'     `"trt_vs_ctrl"`. To test multiple hypotheses jointly (usually used for
 #'     factorial designs), `comparison` can also be `"joint"` or `"omnibus"`. In
@@ -116,11 +116,15 @@
 #'
 #' @section Comparison options:
 #'
-#' - `comparison = "pairwise"`: This method computes all possible unique
-#'   differences between pairs of levels of the focal predictor. For example, if
-#'   a factor has levels A, B, and C, it would compute A-B, A-C, and B-C.
+#' - `comparison = "pairwise"` (default): This method computes all possible
+#'   unique differences between pairs of levels of the focal predictor. For
+#'   example, if a factor has levels A, B, and C, it would compute A-B, A-C, and
+#'   B-C. The formula notation would be `comparison = difference ~ pairwise`.
 #' - `comparison = "revpairwise"`: Like `"pairwise"`, but reverses the order
 #'   of levels when comparing, e.g. B-A, C-A, and C-B.
+#' - `comparison = "ratio"`: This method computes all possible unique ratios
+#'   between pairs of levels of the focal predictor (not differences, like the
+#'   default). It is basically a shortcut for `comparison = ratio ~ pairwise`.
 #' - `comparison = "reference"`: This compares each level of the focal predictor
 #'   to a specified reference level (by default, the first level). For example,
 #'   if levels are A, B, C, and A is the reference, it computes B-A and C-A.

R/format.R

@@ -307,8 +307,9 @@ format.marginaleffects_contrasts <- function(
   }
 
   # check type of contrast
-  is_ratio_comparison <- inherits(comparison, "formula") &&
-    identical(deparse(comparison[[2]]), "ratio")
+  is_ratio_comparison <- (inherits(comparison, "formula") &&
+    identical(deparse(comparison[[2]]), "ratio")) ||
+    identical(comparison, "ratio")
 
   # Column name for coefficient - fix needed for contrasting slopes and ratios
   colnames(x)[colnames(x) == "Slope"] <- "Difference"

R/get_marginalcontrasts.R

@@ -450,8 +450,14 @@ get_marginalcontrasts <- function(
       }
       # for some comparisons, we need an empty left-hand side. else, we default
       # to "difference".
-      formula_lhs <- switch(comparison, poly = , helmert = "", "difference")
-      formula_rhs <- comparison
+      formula_lhs <- switch(
+        comparison,
+        poly = ,
+        helmert = "",
+        ratio = "ratio",
+        "difference"
+      )
+      formula_rhs <- switch(comparison, ratio = "pairwise", comparison)
     }
     if (omnibus_test) {
       comparison <- NULL
@@ -553,6 +559,7 @@ get_marginalcontrasts <- function(
 .valid_hypothesis_strings <- function() {
   c(
     "pairwise",
+    "ratio",
     "reference",
     "sequential",
     "meandev",

tests/testthat/test-estimate_contrasts.R

@@ -1974,3 +1974,23 @@ test_that("estimate_contrast, don't let group labels appear in comparison labels
     )
   )
 })
+
+
+test_that("estimate_contrast, shortcut 'ratio' works", {
+  skip_if_not_installed("datawizard")
+  data(stigma, package = "modelbased")
+
+  stigma$symptoms_unreal <- datawizard::recode_into(
+    symptoms_unreal %in% c("strongly disagree", "disagree") ~ "(strongly) disagree",
+    symptoms_unreal %in% c("strongly agree", "agree") ~ "(strongly) agree",
+    data = stigma
+  )
+
+  stigma$symptoms_unreal <- as.factor(stigma$symptoms_unreal)
+  stigma$symptoms_unreal <- relevel(stigma$symptoms_unreal, ref = "(strongly) disagree")
+
+  m <- glm(symptoms_unreal ~ sex, data = stigma, family = binomial())
+  out <- estimate_contrasts(m, "sex", comparison = "ratio")
+  expect_named(out, c("Level1", "Level2", "Ratio", "SE", "CI_low", "CI_high", "z", "p"))
+  expect_equal(out$Ratio, 6.14634, tolerance = 1e-4)
+})