Easy 'emmeans' and 'emtrends' — get_emcontrasts • modelbased

The get_emmeans() function is a wrapper to facilitate the usage of emmeans::emmeans() and emmeans::emtrends(), providing a somewhat simpler and intuitive API to find the specifications and variables of interest. It is meanly made to for the developers to facilitate the organization and debugging, and end-users should rather use the estimate_*() series of functions.

Usage

get_emcontrasts(
  model,
  contrast = NULL,
  at = NULL,
  fixed = NULL,
  transform = "none",
  method = "pairwise",
  ...
)

model_emcontrasts(
  model,
  contrast = NULL,
  at = NULL,
  fixed = NULL,
  transform = "none",
  method = "pairwise",
  ...
)

get_emmeans(
  model,
  at = "auto",
  fixed = NULL,
  transform = "response",
  levels = NULL,
  modulate = NULL,
  ...
)

model_emmeans(
  model,
  at = "auto",
  fixed = NULL,
  transform = "response",
  levels = NULL,
  modulate = NULL,
  ...
)

get_emtrends(
  model,
  trend = NULL,
  at = NULL,
  fixed = NULL,
  levels = NULL,
  modulate = NULL,
  ...
)

model_emtrends(
  model,
  trend = NULL,
  at = NULL,
  fixed = NULL,
  levels = NULL,
  modulate = NULL,
  ...
)

Arguments

model: A statistical model.
contrast: A character vector indicating the name of the variable(s) for which to compute the contrasts.
at: The predictor variable(s) at which to evaluate the desired effect / mean / contrasts. Other predictors of the model that are not included here will be collapsed and "averaged" over (the effect will be estimated across them).
fixed: A character vector indicating the names of the predictors to be "fixed" (i.e., maintained), so that the estimation is made at these values.
transform: Is passed to the type argument in emmeans::emmeans(). See this vignette. Can be "none" (default for contrasts), "response" (default for means), "mu", "unlink", "log". "none" will leave the values on scale of the linear predictors. "response" will transform them on scale of the response variable. Thus for a logistic model, "none" will give estimations expressed in log-odds (probabilities on logit scale) and "response" in terms of probabilities.
method: Contrast method. See same argument in emmeans::contrast.
...: Other arguments passed for instance to insight::get_datagrid().
levels, modulate: Deprecated, use at instead.
trend: A character indicating the name of the variable for which to compute the slopes.

Examples

if (require("emmeans", quietly = TRUE)) {
  # Basic usage
  model <- lm(Sepal.Width ~ Species, data = iris)
  get_emcontrasts(model)

  # Dealing with interactions
  model <- lm(Sepal.Width ~ Species * Petal.Width, data = iris)
  # By default: selects first factor
  get_emcontrasts(model)
  # Can also run contrasts between points of numeric
  get_emcontrasts(model, contrast = "Petal.Width", length = 3)
  # Or both
  get_emcontrasts(model, contrast = c("Species", "Petal.Width"), length = 2)
  # Or with custom specifications
  estimate_contrasts(model, contrast = c("Species", "Petal.Width=c(1, 2)"))
  # Can fixate the numeric at a specific value
  get_emcontrasts(model, fixed = "Petal.Width")
  # Or modulate it
  get_emcontrasts(model, at = "Petal.Width", length = 4)
}
#> No variable was specified for contrast estimation. Selecting `contrast = "Species"`.
#> No variable was specified for contrast estimation. Selecting `contrast = "Species"`.
#> NOTE: Results may be misleading due to involvement in interactions
#> NOTE: Results may be misleading due to involvement in interactions
#> No variable was specified for contrast estimation. Selecting `contrast = "Species"`.
#> No variable was specified for contrast estimation. Selecting `contrast = "Species"`.
#> Petal.Width = 0.1:
#>  contrast               estimate    SE  df t.ratio p.value
#>  setosa - versicolor      1.8275 0.279 144   6.550  <.0001
#>  setosa - virginica       1.5479 0.312 144   4.955  <.0001
#>  versicolor - virginica  -0.2797 0.406 144  -0.689  0.7703
#> 
#> Petal.Width = 0.9:
#>  contrast               estimate    SE  df t.ratio p.value
#>  setosa - versicolor      1.6544 0.288 144   5.743  <.0001
#>  setosa - virginica       1.7125 0.325 144   5.276  <.0001
#>  versicolor - virginica   0.0581 0.208 144   0.280  0.9577
#> 
#> Petal.Width = 1.7:
#>  contrast               estimate    SE  df t.ratio p.value
#>  setosa - versicolor      1.4812 0.600 144   2.467  0.0390
#>  setosa - virginica       1.8771 0.597 144   3.144  0.0057
#>  versicolor - virginica   0.3959 0.113 144   3.502  0.0018
#> 
#> Petal.Width = 2.5:
#>  contrast               estimate    SE  df t.ratio p.value
#>  setosa - versicolor      1.3080 0.954 144   1.371  0.3587
#>  setosa - virginica       2.0417 0.922 144   2.214  0.0722
#>  versicolor - virginica   0.7337 0.272 144   2.699  0.0212
#> 
#> P value adjustment: tukey method for comparing a family of 3 estimates 
model <- lm(Sepal.Length ~ Species + Petal.Width, data = iris)

if (require("emmeans", quietly = TRUE)) {
  # By default, 'at' is set to "Species"
  get_emmeans(model)

  # Overall mean (close to 'mean(iris$Sepal.Length)')
  get_emmeans(model, at = NULL)

  # One can estimate marginal means at several values of a 'modulate' variable
  get_emmeans(model, at = "Petal.Width", length = 3)

  # Interactions
  model <- lm(Sepal.Width ~ Species * Petal.Length, data = iris)

  get_emmeans(model)
  get_emmeans(model, at = c("Species", "Petal.Length"), length = 2)
  get_emmeans(model, at = c("Species", "Petal.Length = c(1, 3, 5)"), length = 2)
}
#> We selected `at = c("Species")`.
#> We selected `at = c("Species")`.
#> NOTE: Results may be misleading due to involvement in interactions
#>  Species    Petal.Length emmean     SE  df lower.CL upper.CL
#>  setosa                1   3.25 0.1282 144    2.995     3.50
#>  versicolor            1   1.55 0.3166 144    0.924     2.18
#>  virginica             1   1.91 0.3753 144    1.165     2.65
#>  setosa                3   4.02 0.4026 144    3.229     4.82
#>  versicolor            3   2.30 0.1291 144    2.043     2.55
#>  virginica             3   2.38 0.2137 144    1.954     2.80
#>  setosa                5   4.80 0.9216 144    2.979     6.62
#>  versicolor            5   3.05 0.0840 144    2.881     3.21
#>  virginica             5   2.84 0.0636 144    2.719     2.97
#> 
#> Confidence level used: 0.95 
if (require("emmeans")) {
  model <- lm(Sepal.Width ~ Species * Petal.Length, data = iris)

  get_emtrends(model)
  get_emtrends(model, at = "Species")
  get_emtrends(model, at = "Petal.Length")
  get_emtrends(model, at = c("Species", "Petal.Length"))

  model <- lm(Petal.Length ~ poly(Sepal.Width, 4), data = iris)
  get_emtrends(model)
  get_emtrends(model, at = "Sepal.Width")
}
#> No numeric variable was specified for slope estimation. Selecting `trend = "Petal.Length"`.
#> No numeric variable was specified for slope estimation. Selecting `trend = "Petal.Length"`.
#> No numeric variable was specified for slope estimation. Selecting `trend = "Petal.Length"`.
#> NOTE: Results may be misleading due to involvement in interactions
#> No numeric variable was specified for slope estimation. Selecting `trend = "Petal.Length"`.
#> No numeric variable was specified for slope estimation. Selecting `trend = "Sepal.Width"`.
#> No numeric variable was specified for slope estimation. Selecting `trend = "Sepal.Width"`.
#>  Sepal.Width Sepal.Width.trend    SE  df lower.CL upper.CL
#>         2.00             7.484 5.418 145   -3.225   18.192
#>         2.27             3.779 2.093 145   -0.358    7.916
#>         2.53             0.831 0.765 145   -0.681    2.342
#>         2.80            -1.337 0.706 145   -2.732    0.058
#>         3.07            -2.699 0.543 145   -3.772   -1.626
#>         3.33            -3.231 0.607 145   -4.430   -2.032
#>         3.60            -2.909 0.838 145   -4.564   -1.254
#>         3.87            -1.708 1.009 145   -3.702    0.287
#>         4.13             0.398 2.392 145   -4.330    5.125
#>         4.40             3.431 5.798 145   -8.028   14.890
#> 
#> Confidence level used: 0.95