VetResearchLMM (version 1.1.0)

emmeans_mixed_model: Estimated Marginal Means for a Fitted Mixed Model

Description

Compute estimated marginal means or pairwise comparisons for a fitted linear mixed model using the optional emmeans package.

Usage

emmeans_mixed_model(
  model,
  specs,
  pairwise = FALSE,
  method = "pairwise",
  adjust = "tukey",
  ...
)

Value

An emmGrid object from emmeans. With pairwise = FALSE, this contains estimated marginal means. With pairwise = TRUE, this contains the requested contrasts.

Arguments

model

A fitted model object, typically from lme4::lmer(), lmerTest::lmer(), or nlme::lme().

specs

Specifications for the marginal means, passed to emmeans::emmeans(); for example, ~ dose or ~ dose | Drug.

pairwise

Logical. If FALSE, return the estimated marginal means. If TRUE, return contrasts computed from those marginal means.

method

Contrast method passed to emmeans::contrast() when pairwise = TRUE. The default is "pairwise".

adjust

Multiplicity adjustment passed to emmeans::contrast() when pairwise = TRUE. The default is "tukey". Use NULL to leave the adjustment unspecified.

...

Additional arguments passed to emmeans::emmeans().

Details

Estimated marginal means, also called least-squares means, summarize model predictions for factor levels after accounting for the fitted model structure. They are useful after mixed model fitting because fixed-effect coefficients are often expressed relative to contrast coding, while marginal means and their contrasts are closer to the scientific comparisons shown in the book examples.

This helper complements report_mixed_model(). Use report_mixed_model() for narrative model interpretation and emmeans_mixed_model() for post hoc inference, estimated marginal means, and pairwise comparisons.

The helper keeps emmeans optional. It does not refit the model or change the estimates; it delegates marginal-mean calculations to emmeans::emmeans() and, when requested, contrasts to emmeans::contrast().

References

Lenth, R. V. (2024). emmeans: Estimated Marginal Means, aka Least-Squares Means. R package. See utils::citation("emmeans").

Duchateau, L., Janssen, P., and Rowlands, G. J. (1998). Linear Mixed Models: An Introduction with Applications in Veterinary Research. International Livestock Research Institute.

See Also

report_mixed_model(), emmeans::emmeans(), emmeans::contrast().

Examples

if (requireNamespace("lme4", quietly = TRUE) &&
    requireNamespace("emmeans", quietly = TRUE)) {
  data(ex125, package = "VetResearchLMM")
  fit <- lme4::lmer(
    Pcv ~ dose * Drug + (1 | Region / Drug),
    data = ex125,
    REML = TRUE
  )

  emmeans_mixed_model(fit, ~ dose | Drug, lmer.df = "asymptotic")
  emmeans_mixed_model(
    fit,
    ~ dose | Drug,
    pairwise = TRUE,
    lmer.df = "asymptotic"
  )
}