marginaleffects (version 0.3.3)

datagrid: Generate a data grid of "typical," "counterfactual," or user-specified values for use in the newdata argument of the marginaleffects or predictions functions.

Description

Generate a data grid of "typical," "counterfactual," or user-specified values for use in the newdata argument of the marginaleffects or predictions functions.

Usage

datagrid(
  ...,
  model = NULL,
  newdata = NULL,
  grid.type = "typical",
  FUN.character = Mode,
  FUN.factor = Mode,
  FUN.logical = Mode,
  FUN.numeric = function(x) mean(x, na.rm = TRUE),
  FUN.other = function(x) mean(x, na.rm = TRUE)
)

Arguments

...

named arguments with vectors of values for user-specified variables. The output will include all combinations of these variables (see Examples below.)

model

Model object

newdata

data.frame (one and only one of the model and newdata arguments

grid.type

character

• "typical": variables whose values are not explicitly specified by the user in ... are set to their mean or mode, or to the output of the functions supplied to FUN.type arguments.

• "counterfactual": the entire dataset is duplicated for each combination of the variable values specified in .... Variables not explicitly supplied to datagrid() are set to their observed values in the original dataset.

FUN.character

the function to be applied to character variables.

FUN.factor

the function to be applied to factor variables.

FUN.logical

the function to be applied to factor variables.

FUN.numeric

the function to be applied to numeric variables.

FUN.other

the function to be applied to other variable types.

Value

A data.frame in which each row corresponds to one combination of the named predictors supplied by the user via the ... dots. Variables which are not explicitly defined are held at their mean or mode.

Details

If datagrid is used in a marginaleffects or predictions call as the newdata argument, users do not need to specify the model or newdata argument. The data is extracted automatically from the model.

If users supply a model, the data used to fit that model is retrieved using the insight::get_data function.

Examples

# NOT RUN {
# The output only has 2 rows, and all the variables except `hp` are at their
# mean or mode.
datagrid(newdata = mtcars, hp = c(100, 110))

# We get the same result by feeding a model instead of a data.frame
mod <- lm(mpg ~ hp, mtcars)
datagrid(model = mod, hp = c(100, 110))

# Use in `marginaleffects` to compute "Typical Marginal Effects". When used
# in `marginaleffects()` or `predictions()` we do not need to specify the
#`model` or `newdata` arguments.
marginaleffects(mod, newdata = datagrid(hp = c(100, 110)))

# The full dataset is duplicated with each observation given counterfactual
# values of 100 and 110 for the `hp` variable. The original `mtcars` includes
# 32 rows, so the resulting dataset includes 64 rows.
dg <- datagrid(newdata = mtcars, hp = c(100, 110), grid.type = "counterfactual")
nrow(dg)

# We get the same result by feeding a model instead of a data.frame
mod <- lm(mpg ~ hp, mtcars)
dg <- datagrid(model = mod, hp = c(100, 110), grid.type = "counterfactual")
nrow(dg)
# }