docs

Author: strengejacke

NEWS.md

@@ -12,6 +12,9 @@
 - The `"marginaleffects"` backend for `estimate_means()` is now fully implemented
   and no longer work-in-progress.
 
+- `estimate_expectation()` and related functions also get a `by` argument, as
+  alternative to create a datagrid for the `data` argument.
+
 # modelbased 0.8.9
 
 - Fixed issues related to updates of other *easystats* packages.

R/estimate_predicted.R

@@ -129,11 +129,21 @@
 #' @inheritParams estimate_means
 #' @inheritParams bayestestR::describe_posterior
 #' @param data A data frame with model's predictors to estimate the response. If
-#'   `NULL`, the model's data is used. If "grid", the model matrix is obtained
-#'   (through [insight::get_datagrid()]).
+#' `NULL`, the model's data is used. If `"grid"`, the model matrix is obtained
+#' (through [insight::get_datagrid()]).
+#' @param by The predictor variable(s) at which to estimate the response. Other
+#' predictors of the model that are not included here will be set to their mean
+#' value (for numeric predictors), reference level (for factors) or mode (other
+#' types). The `by` argument will be used to create a data grid via
+#' `insight::get_datagrid()`, which will then be used as `data` argument. Thus,
+#' you cannot specify both `data` and `by` but only of these two arguments.
 #' @param ... You can add all the additional control arguments from
-#'   [insight::get_datagrid()] (used when `data = "grid"`) and
-#'   [insight::get_predicted()].
+#' [insight::get_datagrid()] (used when `data = "grid"`) and
+#' [insight::get_predicted()].
+#'
+#' @return A data frame of predicted values and uncertainty intervals, with
+#' class `"estimate_predicted"`. Methods for [`visualisation_recipe()`][visualisation_recipe.estimate_predicted]
+#' and [`plot()`][visualisation_recipe.estimate_predicted] are available.
 #'
 #' @examplesIf all(insight::check_if_installed(c("see", "lme4", "rstanarm"), quietly = TRUE))
 #' library(modelbased)
@@ -176,18 +186,17 @@
 #' estimate_expectation(model)
 #' estimate_relation(model)
 #' }
-#' @return A data frame of predicted values and uncertainty intervals, with
-#' class `"estimate_predicted"`. Methods for [`visualisation_recipe()`][visualisation_recipe.estimate_predicted]
-#' and [`plot()`][visualisation_recipe.estimate_predicted] are available.
 #' @export
 estimate_expectation <- function(model,
                                  data = NULL,
+                                 by = NULL,
                                  ci = 0.95,
                                  keep_iterations = FALSE,
                                  ...) {
   .estimate_predicted(
     model,
     data = data,
+    by = by,
     ci = ci,
     keep_iterations = keep_iterations,
     predict = "expectation",
@@ -200,12 +209,14 @@ estimate_expectation <- function(model,
 #' @export
 estimate_link <- function(model,
                           data = "grid",
+                          by = NULL,
                           ci = 0.95,
                           keep_iterations = FALSE,
                           ...) {
   .estimate_predicted(
     model,
     data = data,
+    by = by,
     ci = ci,
     keep_iterations = keep_iterations,
     predict = "link",
@@ -217,12 +228,14 @@ estimate_link <- function(model,
 #' @export
 estimate_prediction <- function(model,
                                 data = NULL,
+                                by = NULL,
                                 ci = 0.95,
                                 keep_iterations = FALSE,
                                 ...) {
   .estimate_predicted(
     model,
     data = data,
+    by = by,
     ci = ci,
     keep_iterations = keep_iterations,
     predict = "prediction",
@@ -234,12 +247,14 @@ estimate_prediction <- function(model,
 #' @export
 estimate_relation <- function(model,
                               data = "grid",
+                              by = NULL,
                               ci = 0.95,
                               keep_iterations = FALSE,
                               ...) {
   .estimate_predicted(
     model,
     data = data,
+    by = by,
     ci = ci,
     keep_iterations = keep_iterations,
     predict = "expectation",
@@ -254,10 +269,16 @@ estimate_relation <- function(model,
 #' @keywords internal
 .estimate_predicted <- function(model,
                                 data = "grid",
+                                by = NULL,
                                 predict = "expectation",
                                 ci = 0.95,
                                 keep_iterations = FALSE,
                                 ...) {
+  # only "by" or "data", but not both
+  if (!is.null(by) && !is.null(data)) {
+    insight::format_error("You can only specify one of `by` or `data`, but not both.")
+  }
+
   # call "get_data()" only once...
   model_data <- insight::get_data(model, verbose = FALSE)
   is_model <- insight::is_model(model)
@@ -275,6 +296,11 @@ estimate_relation <- function(model,
     is_nullmodel <- FALSE
   }
 
+  # if "by" is provided, get datagrid
+  if (!is.null(by)) {
+    data <- insight::get_datagrid(model, by = by, include_response = is_nullmodel, ...)
+  }
+
   is_grid <- identical(data, "grid")
 
   # check for correct attributes - a data frame of class `datagrid` may

R/estimate_slopes.R

@@ -16,13 +16,13 @@
 #' @inheritParams estimate_means
 #'
 #' @details
-#'
 #' The [estimate_slopes()], [estimate_means()] and [estimate_contrasts()]
 #' functions are forming a group, as they are all based on *marginal*
-#' estimations (estimations based on a model). All three are also built on the
-#' \pkg{emmeans} package, so reading its documentation (for instance for
-#' [emmeans::emmeans()] and [emmeans::emtrends()]) is recommended to understand
-#' the idea behind these types of procedures.
+#' estimations (estimations based on a model). All three are built on the
+#' **emmeans** or **marginaleffects** package (depending on the `backend`
+#' argument), so reading its documentation (for instance [emmeans::emmeans()],
+#' [emmeans::emtrends()] or this [website](https://marginaleffects.com/) is
+#' recommended to understand the idea behind these types of procedures.
 #'
 #' - Model-based **predictions** is the basis for all that follows. Indeed,
 #' the first thing to understand is how models can be used to make predictions
@@ -70,7 +70,9 @@
 #' the effect of x averaged over all conditions, or instead within each
 #' condition (`using [estimate_slopes]`).
 #'
-#' @examplesIf require("emmeans") && require("ggplot2") && require("see")
+#' @return A data.frame of class `estimate_slopes`.
+#'
+#' @examplesIf all(insight::check_if_installed(c("emmeans", "mgcv", "ggplot2", "see"), quietly = TRUE))
 #' # Get an idea of the data
 #' ggplot(iris, aes(x = Petal.Length, y = Sepal.Width)) +
 #'   geom_point(aes(color = Species)) +
@@ -86,10 +88,8 @@
 #'
 #' # Plot it
 #' plot(slopes)
-#'
 #' standardize(slopes)
 #'
-#' @examplesIf require("mgcv") && require("emmeans") && require("see")
 #' model <- mgcv::gam(Sepal.Width ~ s(Petal.Length), data = iris)
 #' slopes <- estimate_slopes(model, by = "Petal.Length", length = 50)
 #' summary(slopes)
@@ -102,7 +102,6 @@
 #' )
 #' summary(slopes)
 #' plot(slopes)
-#' @return A data.frame of class `estimate_slopes`.
 #' @export
 estimate_slopes <- function(model,
                             trend = NULL,