R: Compute joint tests of the terms in a model

joint_tests {emmeans} | R Documentation

## 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, ...)

### Arguments

`object` | a fitted model or an `emmGrid`. If a fitted model, it is replaced by `ref_grid(object, cov.reduce = range, ...)`
`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.

### See Also

`test`

### 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)                      # ref grid uses mean(female) = 0.4
    joint_tests(toy.cov, cov.reduce = FALSE)  # ref grid uses female = c(0, 1)
    joint_tests(toy.cov, at = list(female = c(-1, 1)))  # center on intercept

    # -- 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

[Package emmeans version 1.1.3 Index]