emmeans (version 1.2.4)

regrid: Reconstruct a reference grid with a new transformation

Description

The typical use of this function is to cause EMMs to be computed on a different scale, e.g., the back-transformed scale rather than the linear-predictor scale. In other words, if you want back-transformed results, do you want to average and then back-transform, or back-transform and then average?

Usage

regrid(object, transform = c("response", "mu", "unlink", "log", "none"),
  inv.log.lbl = "response", predict.type)

Arguments

object

An object of class emmGrid

transform

Character or logical value. If "response" or "mu", the inverse transformation is applied to the estimates in the grid (but if there is both a link function and a response transformation, "mu" back-transforms only the link part); if "log", the results are formulated as if the response had been log-transformed; if "none", predictions thereof are on the same scale as in object, and any internal transformation information is preserved. For compatibility with past versions, transform may also be logical; TRUE is taken as "response", and FALSE as "none".

inv.log.lbl

Character value. This applies only when transform = "log", and is used to label the predictions if subsequently summarized with type = "response".

predict.type

Character value. If provided, the returned object is updated with the given type, e.g., "response". See update.emmGrid.

Value

An emmGrid object with the requested changes

Details

The regrid function reparameterizes an existing ref.grid so that its linfct slot is the identity matrix and its bhat slot consists of the estimates at the grid points. If transform is TRUE, the inverse transform is applied to the estimates. Outwardly, when transform = "response", the result of summary.emmGrid after applying regrid is identical to the summary of the original object using type="response". But subsequent EMMs or contrasts will be conducted on the new scale -- which is the reason this function exists.

In cases where the degrees of freedom depended on the linear function being estimated, the d.f. from the reference grid are saved, and a kind of “containment” method is substituted in the returned object whereby the calculated d.f. for a new linear function will be the minimum d.f. among those having nonzero coefficients. This is kind of an ad hoc method, and it can over-estimate the degrees of freedom in some cases.

Examples

# NOT RUN {
pigs.lm <- lm(log(conc) ~ source + factor(percent), data = pigs)

# This will yield EMMs as GEOMETRIC means of concentrations:
emmeans(pigs.lm, "source", type = "response")
# NOTE: pairs() of the above will be RATIOS of these results

# This will yield EMMs as ARITHMETIC means of concentrations:
emmeans(regrid(ref_grid(pigs.lm, transform = "response")), "source")
# Same thing, made simpler:
emmeans(pigs.lm, "source", transform = "response")
# NOTE: pairs() of the above will be DIFFERENCES of these results
# }