emtrends: 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(model, specs, var, delta.var = 0.01 * rng, data,
  transform = c("none", "response"), ...)

Arguments

model

A supported model object (not a reference grid)

specs

Specifications for what marginal trends are desired -- as in emmeans

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/100 of the range of var over the dataset.

data

As in ref_grid, you may use this argument to supply the dataset used in fitting the model, for situations where it is not possible to reconstruct the data. Otherwise, leave it missing.

transform

If object has a response transformation or link function, then specifying transform = "response" will cause emtrends to calculate the trends after back-transforming to the response scale. This is done using the chain rule, and standard errors are estimated via the delta method. With transform = "none" (the default), the trends are calculated on the scale of the linear predictor, without back-transforming it. This argument works similarly to the transform argument in ref_grid, in that the returned object is re-gridded to the new scale (see also regrid).

...

Additional arguments passed to other methods or to ref_grid

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 model 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.

Examples

Run this code

# NOT RUN {
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)))

# }