# emtrends: Estimated marginal means of linear trends In emmeans: Estimated Marginal Means, aka Least-Squares Means

 emtrends R Documentation

## Estimated marginal means of linear trends

### Description

The `emtrends` function is useful when a fitted model involves a numerical predictor `x` interacting with another predictor `a` (typically a factor). Such models specify that `x` has a different trend depending on `a`; thus, it may be of interest to estimate and compare those trends. Analogous to the `emmeans` setting, we construct a reference grid of these predicted trends, and then possibly average them over some of the predictors in the grid.

### Usage

``````emtrends(object, specs, var, delta.var = 0.001 * rng, max.degree = 1, ...)
``````

### Arguments

 `object` A supported model object (not a reference grid) `specs` Specifications for what marginal trends are desired – as in `emmeans`. If `specs` is missing or `NULL`, `emmeans` is not run and the reference grid for specified trends is returned. `var` Character value giving the name of a variable with respect to which a difference quotient of the linear predictors is computed. In order for this to be useful, `var` should be a numeric predictor that interacts with at least one factor in `specs`. Then instead of computing EMMs, we compute and compare the slopes of the `var` trend over levels of the specified other predictor(s). As in EMMs, marginal averages are computed for the predictors in `specs` and `by`. See also the “Generalizations” section below. `delta.var` The value of h to use in forming the difference quotient `(f(x+h) - f(x))/h`. Changing it (especially changing its sign) may be necessary to avoid numerical problems such as logs of negative numbers. The default value is 1/1000 of the range of `var` over the dataset. `max.degree` Integer value. The maximum degree of trends to compute (this is capped at 5). If greater than 1, an additional factor `degree` is added to the grid, with corresponding numerical derivatives of orders `1, 2, ..., max.degree` as the estimates. `...` Additional arguments passed to `ref_grid` or `emmeans` as appropriate. See Details.

### Details

The function works by constructing reference grids for `object` with various values of `var`, and then calculating difference quotients of predictions from those reference grids. Finally, `emmeans` is called with the given `specs`, thus computing marginal averages as needed of the difference quotients. Any `...` arguments are passed to the `ref_grid` and `emmeans`; examples of such optional arguments include optional arguments (often `mode`) that apply to specific models; `ref_grid` options such as `data`, `at`, `cov.reduce`, `mult.names`, `nesting`, or `transform`; and `emmeans` options such as `weights` (but please avoid `trend` or `offset`.

### Value

An `emmGrid` or `emm_list` object, according to `specs`. See `emmeans` for more details on when a list is returned.

### Generalizations

Instead of a single predictor, the user may specify some monotone function of one variable, e.g., `var = "log(dose)"`. If so, the chain rule is applied. Note that, in this example, if `object` contains `log(dose)` as a predictor, we will be comparing the slopes estimated by that model, whereas specifying `var = "dose"` would perform a transformation of those slopes, making the predicted trends vary depending on `dose`.

### Note

In earlier versions of `emtrends`, the first argument was named `model` rather than `object`. (The name was changed because of potential mis-matching with a `mode` argument, which is an option for several types of models.) For backward compatibility, `model` still works provided all arguments are named.

It is important to understand that trends computed by `emtrends` are not equivalent to polynomial contrasts in a parallel model where `var` is regarded as a factor. That is because the model `object` here is assumed to fit a smooth function of `var`, and the estimated trends reflect local behavior at particular value(s) of `var`; whereas when `var` is modeled as a factor and polynomial contrasts are computed, those contrasts represent the global pattern of changes over all levels of `var`.

See the `pigs.poly` and `pigs.fact` examples below for an illustration. The linear and quadratic trends depend on the value of `percent`, but the cubic trend is constant (because that is true of a cubic polynomial, which is the underlying model). The cubic contrast in the factorial model has the same P value as for the cubic trend, again because the cubic trend is the same everywhere.

`emmeans`, `ref_grid`

### Examples

``````fiber.lm <- lm(strength ~ diameter*machine, data=fiber)
# Obtain slopes for each machine ...
( fiber.emt <- emtrends(fiber.lm, "machine", var = "diameter") )
# ... and pairwise comparisons thereof
pairs(fiber.emt)

# Suppose we want trends relative to sqrt(diameter)...
emtrends(fiber.lm, ~ machine | diameter, var = "sqrt(diameter)",
at = list(diameter = c(20, 30)))

# Obtaining a reference grid
mtcars.lm <- lm(mpg ~ poly(disp, degree = 2) * (factor(cyl) + factor(am)), data = mtcars)

# Center trends at mean disp for each no. of cylinders
mtcTrends.rg <- emtrends(mtcars.lm, var = "disp",
cov.reduce = disp ~ factor(cyl))
summary(mtcTrends.rg)  # estimated trends at grid nodes
emmeans(mtcTrends.rg, "am", weights = "prop")

### Higher-degree trends ...

pigs.poly <- lm(conc ~ poly(percent, degree = 3), data = pigs)
emt <- emtrends(pigs.poly, ~ degree | percent, "percent", max.degree = 3,
at = list(percent = c(9, 13.5, 18)))
# note: 'degree' is an extra factor created by 'emtrends'

summary(emt, infer = c(TRUE, TRUE))

# Compare above results with poly contrasts when 'percent' is modeled as a factor ...
pigs.fact <- lm(conc ~ factor(percent), data = pigs)
emm <- emmeans(pigs.fact, "percent")

contrast(emm, "poly")
# Some P values are comparable, some aren't! See Note in documentation
``````

emmeans documentation built on Oct. 18, 2023, 1:13 a.m.