Docs for get datagrid (#979)

* use new version of marginal effects #978 * enhance docs for get_datagrid split off * Update test-get_datagrid.R * docs * fix * styler * fix --------- Co-authored-by: Daniel <[email protected]>
easystats · Dec 13, 2024 · 19fc4f5 · 19fc4f5
1 parent 852dac1
commit 19fc4f5
Show file tree

Hide file tree

Showing 6 changed files with 122 additions and 18 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -148,7 +148,7 @@ Suggests:
     lmtest,
     logistf,
     logitr,
-    marginaleffects,
+    marginaleffects (>= 0.24.0.6),
     MASS,
     Matrix,
     mclogit,
@@ -219,3 +219,4 @@ Config/testthat/edition: 3
 Config/testthat/parallel: true
 Config/Needs/website: easystats/easystatstemplate
 Config/Needs/check: stan-dev/cmdstanr
+Remotes: vincentarelbundock/marginaleffects
diff --git a/R/get_datagrid.R b/R/get_datagrid.R
@@ -1,13 +1,16 @@
-#' Create a reference grid
+#' @title Create a reference grid
+#' @name get_datagrid
 #'
+#' @description
 #' Create a reference matrix, useful for visualisation, with evenly spread and
 #' combined values. Usually used to make generate predictions using
 #' [get_predicted()]. See this
 #' [vignette](https://easystats.github.io/modelbased/articles/visualisation_matrix.html)
 #' for a tutorial on how to create a visualisation matrix using this function.
-#' \cr\cr
+#'
 #' Alternatively, these can also be used to extract the "grid" columns from
-#' objects generated by **emmeans** and **marginaleffects**.
+#' objects generated by **emmeans** and **marginaleffects** (see those
+#' [methods][get_datagrid.emmGrid] for more info).
 #'
 #' @param x An object from which to construct the reference grid.
 #' @param by Indicates the _focal predictors_ (variables) for the reference grid
@@ -115,7 +118,9 @@
 #'
 #' @return Reference grid data frame.
 #'
-#' @seealso [get_predicted()]
+#' @seealso [get_predicted()] to extract predictions, for which the data grid
+#' is useful, and see the [methods][get_datagrid.emmGrid] for objects generated
+#' by **emmeans** and **marginaleffects** to extract the "grid" columns.
 #'
 #' @examplesIf require("bayestestR", quietly = TRUE) && require("datawizard", quietly = TRUE)
 #' # Datagrids of variables and dataframes =====================================
@@ -644,7 +649,51 @@ get_datagrid.datagrid <- get_datagrid.visualisation_matrix
 
 # Functions for emmeans/marginaleffects ---------------
 
-#' @rdname get_datagrid
+#' Extract a reference grid from objects created by `{emmeans}` and `{marginaleffects}`
+#'
+#' @param x An object created by a function such as [emmeans::emmeans()],
+#'   [marginaleffects::slopes()], etc.
+#' @param ... Currently not used
+#'
+#' @details
+#' Note that for `{emmeans}` inputs the results is a proper grid (all
+#' combinations of values are represented), except when a nesting structure is
+#' detected. Additionally, when the input is an `emm_list` object, the function
+#' will `rbind()` the data-grids of all the elements in the input.
+#'
+#' For `{marginaleffects}` inputs, the output may very well be a non-grid
+#' result. See examples.
+#'
+#' @return A `data.frame` with key columns that identify the rows in `x`.
+#'
+#' @examples
+#' data("mtcars")
+#' mtcars$cyl <- factor(mtcars$cyl)
+#'
+#' mod <- glm(am ~ cyl + hp + wt,
+#'   family = binomial("logit"),
+#'   data = mtcars
+#' )
+#'
+#' @examplesIf insight::check_if_installed("emmeans", quietly = TRUE)
+#' em1 <- emmeans::emmeans(mod, ~ cyl + hp, at = list(hp = c(100, 150)))
+#' get_datagrid(em1)
+#'
+#' contr1 <- emmeans::contrast(em1, method = "consec", by = "hp")
+#' get_datagrid(contr1)
+#'
+#' eml1 <- emmeans::emmeans(mod, pairwise ~ cyl | hp, at = list(hp = c(100, 150)))
+#' get_datagrid(eml1) # not a "true" grid
+#'
+#' @examplesIf insight::check_if_installed("marginaleffects", quietly = TRUE, minimum_version = "0.24.0.6")
+#' mfx1 <- marginaleffects::slopes(mod, variables = "hp")
+#' get_datagrid(mfx1) # not a "true" grid
+#'
+#' mfx2 <- marginaleffects::slopes(mod, variables = c("hp", "wt"), by = "am")
+#' get_datagrid(mfx2)
+#'
+#' contr2 <- marginaleffects::avg_comparisons(mod)
+#' get_datagrid(contr2) # not a "true" grid
 #' @export
 get_datagrid.emmGrid <- function(x, ...) {
   suppressWarnings({
@@ -675,7 +724,6 @@ get_datagrid.emm_list <- function(x, ...) {
   out[, c(clear_cols, setdiff(colnames(out), clear_cols)), drop = FALSE]
 }
 
-#' @rdname get_datagrid
 #' @export
 get_datagrid.slopes <- function(x, ...) {
   cols_newdata <- colnames(attr(x, "newdata"))

diff --git a/man/get_datagrid.Rd b/man/get_datagrid.Rd
diff --git a/man/get_datagrid.emmGrid.Rd b/man/get_datagrid.emmGrid.Rd
diff --git a/pkgdown/_pkgdown.yaml b/pkgdown/_pkgdown.yaml
@@ -127,6 +127,7 @@ reference:
       - find_parameters.glmmTMB
       - find_parameters.zeroinfl
       - find_parameters.averaging
+      - get_datagrid.emmGrid
       - get_parameters.BGGM
       - get_parameters.emmGrid
       - get_parameters.gamm

diff --git a/tests/testthat/test-get_datagrid.R b/tests/testthat/test-get_datagrid.R
@@ -212,7 +212,6 @@ test_that("get_datagrid - models", {
 
 test_that("get_datagrid - emmeans", {
   skip_if_not_installed("emmeans")
-  skip_on_cran()
 
   data("mtcars")
 
@@ -258,7 +257,6 @@ test_that("get_datagrid - emmeans", {
 
 test_that("get_datagrid - marginaleffects", {
   skip_if_not_installed("marginaleffects")
-  skip_on_cran()
 
   data("mtcars")