R: Add a grouping factor

add_grouping {emmeans} | R Documentation

## Add a grouping factor

### Description

This function adds a grouping factor to an existing reference grid or other `emmGrid` object, such that the levels of an existing factor (call it the reference factor) are mapped to a smaller number of levels of the new grouping factor. The reference factor is then nested in the grouping factor. This facilitates obtaining marginal means of the grouping factor, and contrasts thereof.

### Usage

    add_grouping(object, newname, refname, newlevs)

### Arguments

`object` | An `emmGrid` object
`newname` | Character name of grouping factor to add (different from any existing factor in the grid)
`refname` | Character name of the reference factor
`newlevs` | Character vector or factor of the same length as that of the levels for `refname`. The grouping factor `newname` will have the unique values of `newlevs` as its levels.

### Value

A revised `emmGrid` object having an additional factor named `newname`, and a new nesting structure `refname %in% newname`

### Note

By default, the levels of `newname` will be ordered alphabetically. To dictate a different ordering of levels, supply `newlevs` as a `factor` having its levels in the required order.

### Examples

    fiber.lm <- lm(strength ~ diameter + machine, data = fiber)
    ( frg <- ref_grid(fiber.lm) )

    # Suppose the machines are two different brands
    brands <- factor(c("FiberPro", "FiberPro", "Acme"), levels = c("FiberPro", "Acme"))
    ( gfrg <- add_grouping(frg, "brand", "machine", brands) )

    emmeans(gfrg, "machine")

    emmeans(gfrg, "brand")

[Package emmeans version 1.1.3 Index]