emmeans: joint_tests – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

joint_tests

Compute joint tests of the terms in a model

Description

This function produces an analysis-of-variance-like table based on linear functions of predictors in a model or emmGrid object. Specifically, the function constructs, for each combination of factors (or covariates reduced to two or more levels), a set of (interaction) contrasts via contrast, and then tests them using test with joint = TRUE. Optionally, one or more of the predictors may be used as by variable(s), so that separate tables of tests are produced for each combination of them.

Usage

joint_tests(object, by = NULL, show0df = FALSE, cov.reduce = range, ...)

Arguments

`object, cov.reduce`	`object` is a fitted model or an `emmGrid`. If a fitted model, it is replaced by `ref_grid(object, cov.reduce = cov.reduce, ...)`
`by`	character names of `by` variables. Separate sets of tests are run for each combination of these.
`show0df`	logical value; if `TRUE`, results with zero numerator degrees of freedom are displayed, if `FALSE` they are skipped
`...`	additional arguments passed to `ref_grid` and `emmeans`

Details

In models with only factors, no covariates, we believe these tests correspond to “type III” tests a la SAS, as long as equal-weighted averaging is used and there are no estimability issues. When covariates are present and interact with factors, the results depend on how the covariate is handled in constructing the reference grid. See the example at the end of this documentation. The point that one must always remember is that joint_tests always tests contrasts among EMMs, in the context of the reference grid, whereas type III tests are tests of model coefficients – which may or may not have anything to do with EMMs or contrasts.

Value

a summary_emm object (same as is produced by summary.emmGrid). All effects for which there are no estimable contrasts are omitted from the results.

Examples

pigs.lm <- lm(log(conc) ~ source * factor(percent), data = pigs)

joint_tests(pigs.lm)                     ## will be same as type III ANOVA

joint_tests(pigs.lm, weights = "outer")  ## differently weighted

joint_tests(pigs.lm, by = "source")      ## separate joint tests of 'percent'

### Comparisons with type III tests
toy = data.frame(
    treat = rep(c("A", "B"), c(4, 6)),
    female = c(1, 0, 0, 1,   0, 0, 0, 1, 1, 0 ),
    resp = c(17, 12, 14, 19, 28, 26, 26, 34, 33, 27))
toy.fac = lm(resp ~ treat * factor(female), data = toy)
toy.cov = lm(resp ~ treat * female, data = toy)
# (These two models have identical fitted values and residuals)

joint_tests(toy.fac)
joint_tests(toy.cov)   # female is regarded as a 2-level factor by default

joint_tests(toy.cov, at = list(female = 0.5))
joint_tests(toy.cov, cov.keep = 0)   # i.e., female = mean(toy$female)
joint_tests(toy.cov, at = list(female = 0))

# -- Compare with SAS output -- female as factor --
## Source          DF    Type III SS    Mean Square   F Value   Pr > F
## treat            1    488.8928571    488.8928571    404.60   <.0001
## female           1     78.8928571     78.8928571     65.29   0.0002
## treat*female     1      1.7500000      1.7500000      1.45   0.2741
# 
# -- Compare with SAS output -- female as covariate --
## Source          DF    Type III SS    Mean Square   F Value   Pr > F
## treat            1    252.0833333    252.0833333    208.62   <.0001
## female           1     78.8928571     78.8928571     65.29   0.0002
## female*treat     1      1.7500000      1.7500000      1.45   0.2741

emmeans

Estimated Marginal Means, aka Least-Squares Means

v1.6.0

GPL-2 | GPL-3

Authors

Russell V. Lenth [aut, cre, cph], Paul Buerkner [ctb], Maxime Herve [ctb], Jonathon Love [ctb], Hannes Riebl [ctb], Henrik Singmann [ctb]

Initial release

2021-04-25