Example doesn't work with estimate = "average" (#540)

* Example doesn't work with `estimate = "average"`
Fixes #539

* add test

* fix

* whitespace

Author: strengejacke

DESCRIPTION

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

NEWS.md

@@ -23,6 +23,8 @@
   been removed, because this was slightly misleading. The units were in %-points
   if multiplied by 100, but this multiplication was not done in the output.
 
+* Improved documentation and improved informative messages.
+
 ## Bug fixes
 
 * Fixed issue with `by` in `estimate_contrasts()` when `comparison` was

R/estimate_means.R

@@ -69,13 +69,20 @@
 #'   (causal inference, see _Chatton and Rohrer 2024_).
 #'
 #' You can set a default option for the `estimate` argument via `options()`,
-#' e.g. `options(modelbased_estimate = "average")`. When you set `estimate` to
-#' `"average"`, it calculates the average based only on the data points that
-#' actually exist. This is in particular important for two or more focal
-#' predictors, because it doesn't generate a *complete* grid of all theoretical
-#' combinations of predictor values. Consequently, the output may not include
-#' all the values. `estimate = "population"` is not available for
-#' `estimate_slopes()`.
+#' e.g. `options(modelbased_estimate = "average")`.
+#'
+#' Note following limitations:
+#' - When you set `estimate` to `"average"`, it calculates the average based
+#'   only on the data points that actually exist. This is in particular
+#'   important for two or more focal predictors, because it doesn't generate a
+#'   *complete* grid of all theoretical combinations of predictor values.
+#'   Consequently, the output may not include all the values.
+#' - Filtering the output at values of continuous predictors, e.g.
+#'   `by = "x=1:5"`, in combination with `estimate = "average"` may result in
+#'   returning an empty data frame because of what was described above. In such
+#'   case, you can use `estimate = "typical"` or use the `newdata` argument to
+#'   provide a data grid of predictor values at which to evaluate predictions.
+#' - `estimate = "population"` is not available for `estimate_slopes()`.
 #' @param backend Whether to use `"marginaleffects"` (default) or `"emmeans"` as
 #' a backend. Results are usually very similar. The major difference will be
 #' found for mixed models, where `backend = "marginaleffects"` will also average

R/get_marginalcontrasts.R

@@ -202,9 +202,7 @@ get_marginalcontrasts <- function(
     }
     # sanity check - do we have any rows left?
     if (nrow(out) == 0) {
-      insight::format_error(
-        "No rows left after filtering. Please check your `by` and `contrast` arguments, or use a different option for the `estimate` argument, e.g. `estimate = \"typical\"."
-      )
+      .filter_error("No rows left after filtering.")
     }
   }
   out

R/get_marginalmeans.R

@@ -266,6 +266,11 @@ get_marginalmeans <- function(model,
     insight::format_error(.marginaleffects_errors(out, fun_args))
   }
 
+  # check number of rows - for estimate = "average", no rows might be returned
+  if (nrow(out) == 0) {
+    .filter_error("No rows returned from marginal means.")
+  }
+
   out
 }
 
@@ -438,11 +443,26 @@ get_marginalmeans <- function(model,
     }
     # else, filter values
     means <- datawizard::data_match(means, datagrid[datagrid_info$at_specs$varname])
+    # sanity check - do we have any rows left?
+    if (nrow(means) == 0) {
+      .filter_error("No rows left after filtering.")
+    }
   }
   means
 }
 
 
+# small helper, because we have the same error message in several places
+.filter_error <- function(prefix = "") {
+  insight::format_error(
+    prefix,
+    "Please check your `by` and `contrast` arguments, or try one of the following options:",
+    "1. Use a different option for the `estimate` argument, e.g. `estimate = \"typical\"`.",
+    "2. Use the `newdata` argument to provide a data grid of predictor values at which to evaluate predictions."
+  )
+}
+
+
 # handle attributes -----------------------------------------------------------
 
 # we have following attributes for modelbased-objects:

man/estimate_contrasts.Rd

@@ -65,3 +65,44 @@ test_that("special filtering for by and contrast works", {
   #   )
   # )
 })
+
+
+test_that("filtering throws informative error when zero rows are returned", {
+  set.seed(1234)
+  n <- 365
+  event_start <- 200
+  time <- seq_len(n)
+  event <- c(rep_len(0, event_start), rep_len(1, n - event_start))
+  outcome <- 10 + # 1. Pre-intervention intercept
+    15 * time + # 2. Pre-intervention slope (trend)
+    20 * event + # 3. Level change (a jump of +20)
+    5 * event * time + # 4. Slope change (slope becomes 15 + 5 = 20)
+    rnorm(n, mean = 0, sd = 100) # Add some random noise
+
+  dat <- data.frame(outcome, time, event)
+  mod <- lm(outcome ~ time * event, data = dat)
+  expect_error(
+    estimate_contrasts(mod, contrast = "event", by = "time=200", estimate = "average"),
+    regex = "No rows returned from marginal means"
+  )
+  expect_silent(estimate_contrasts(mod, contrast = "event", by = "time=200"))
+
+  d <- data.frame(event = c(0, 1), time = 200)
+  expect_silent(estimate_contrasts(
+    mod,
+    contrast = "event",
+    by = "time",
+    newdata = d,
+    estimate = "average"
+  ))
+
+  out1 <- estimate_contrasts(mod, contrast = "event", by = "time=200")
+  out2 <- estimate_contrasts(
+    mod,
+    contrast = "event",
+    by = "time",
+    newdata = d,
+    estimate = "average"
+  )
+  expect_equal(out1$Difference, out2$Difference, tolerance = 1e-4)
+})