broom.helpers (version 1.17.0)

tidy_marginal_contrasts: Marginal Contrasts with marginaleffects::avg_comparisons()

Description

Use marginaleffects::avg_comparisons() to estimate marginal contrasts for each variable of a model and return a tibble tidied in a way that it could be used by broom.helpers functions. See marginaleffects::avg_comparisons() for a list of supported models.

Usage

tidy_marginal_contrasts(
  x,
  variables_list = "auto",
  conf.int = TRUE,
  conf.level = 0.95,
  ...
)
variables_to_contrast(
  model,
  interactions = TRUE,
  cross = FALSE,
  var_categorical = "reference",
  var_continuous = 1,
  by_categorical = unique,
  by_continuous = stats::fivenum
)

Arguments

x

(a model object, e.g. glm)
A model to be tidied.

variables_list

(list or string)
A list whose elements will be sequentially passed to variables in marginaleffects::avg_comparisons() (see details below); alternatively, it could also be the string "auto" (default), "cross" or "no_interaction"

conf.int

(logical)
Whether or not to include a confidence interval in the tidied output.

conf.level

(numeric)
The confidence level to use for the confidence interval (between 0 ans 1).

...

Additional parameters passed to marginaleffects::avg_comparisons().

model

(a model object, e.g. glm)
A model.

interactions

(logical)
Should combinations of variables corresponding to interactions be returned?

cross

(logical)
If interaction is TRUE, should "cross-contrasts" be computed? (if FALSE, only the last term of an interaction is passed to variable and the other terms are passed to by)

var_categorical

(predictor values)
Default variable value for categorical variables.

var_continuous

(predictor values)
Default variable value for continuous variables.

by_categorical

(predictor values)
Default by value for categorical variables.

by_continuous

(predictor values)
Default by value for continuous variables.

Details

Marginal contrasts are obtained by calling, for each variable or combination of variables, marginaleffects::avg_comparisons().

tidy_marginal_contrasts() will compute marginal contrasts for each variable or combination of variables, before stacking the results in a unique tibble. This is why tidy_marginal_contrasts() has a variables_list argument consisting of a list of specifications that will be passed sequentially to the variables and the by argument of marginaleffects::avg_comparisons().

Considering a single categorical variable named cat, tidy_marginal_contrasts() will call avg_comparisons(model, variables = list(cat = "reference")) to obtain average marginal contrasts for this variable.

Considering a single continuous variable named cont, tidy_marginalcontrasts() will call avg_comparisons(model, variables = list(cont = 1)) to obtain average marginal contrasts for an increase of one unit.

For a combination of variables, there are several possibilities. You could compute "cross-contrasts" by providing simultaneously several variables to variables and specifying cross = TRUE to marginaleffects::avg_comparisons(). Alternatively, you could compute the contrasts of a first variable specified to variables for the different values of a second variable specified to by.

The helper function variables_to_contrast() could be used to automatically generate a suitable list to be used with variables_list. Each combination of variables should be a list with two named elements: "variables" a list of named elements passed to variables and "by" a list of named elements used for creating a relevant datagrid and whose names are passed to by.

variables_list's default value, "auto", calls variables_to_contrast(interactions = TRUE, cross = FALSE) while "no_interaction" is a shortcut for variables_to_contrast(interactions = FALSE). "cross" calls variables_to_contrast(interactions = TRUE, cross = TRUE)

You can also provide custom specifications (see examples).

By default, average marginal contrasts are computed: contrasts are computed using a counterfactual grid for each value of the variable of interest, before averaging the results. Marginal contrasts at the mean could be obtained by indicating newdata = "mean". Other assumptions are possible, see the help file of marginaleffects::avg_comparisons().

For more information, see vignette("marginal_tidiers", "broom.helpers").

See Also

marginaleffects::avg_comparisons(), tidy_avg_comparisons()

Other marginal_tieders: tidy_all_effects(), tidy_avg_comparisons(), tidy_avg_slopes(), tidy_ggpredict(), tidy_marginal_means(), tidy_marginal_predictions(), tidy_margins()

Examples

if (FALSE) { # interactive()
# Average Marginal Contrasts
df <- Titanic |>
  dplyr::as_tibble() |>
  tidyr::uncount(n) |>
  dplyr::mutate(Survived = factor(Survived, c("No", "Yes")))
mod <- glm(
  Survived ~ Class + Age + Sex,
  data = df, family = binomial
)
tidy_marginal_contrasts(mod)
tidy_plus_plus(mod, tidy_fun = tidy_marginal_contrasts)

mod2 <- lm(Petal.Length ~ poly(Petal.Width, 2) + Species, data = iris)
tidy_marginal_contrasts(mod2)
tidy_marginal_contrasts(
  mod2,
  variables_list = variables_to_predict(
    mod2,
    continuous = 3,
    categorical = "pairwise"
  )
)

# Model with interactions
mod3 <- glm(
  Survived ~ Sex * Age + Class,
  data = df, family = binomial
)
tidy_marginal_contrasts(mod3)
tidy_marginal_contrasts(mod3, "no_interaction")
tidy_marginal_contrasts(mod3, "cross")
tidy_marginal_contrasts(
  mod3,
  variables_list = list(
    list(variables = list(Class = "pairwise"), by = list(Sex = unique)),
    list(variables = list(Age = "all")),
    list(variables = list(Class = "sequential", Sex = "reference"))
  )
)

mod4 <- lm(Sepal.Length ~ Petal.Length * Petal.Width + Species, data = iris)
tidy_marginal_contrasts(mod4)
tidy_marginal_contrasts(
  mod4,
  variables_list = list(
    list(
      variables = list(Species = "sequential"),
      by = list(Petal.Length = c(2, 5))
    ),
    list(
      variables = list(Petal.Length = 2),
      by = list(Species = unique, Petal.Width = 2:4)
    )
  )
)

# Marginal Contrasts at the Mean
tidy_marginal_contrasts(mod, newdata = "mean")
tidy_marginal_contrasts(mod3, newdata = "mean")
}