emmeans: regrid – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

regrid

Reconstruct a reference grid with a new transformation or simulations

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", "none", "pass",
  links), inv.link.lbl = "response", predict.type,
  bias.adjust = get_emm_option("back.bias.adj"), sigma, N.sim,
  sim = mvtnorm::rmvnorm, ...)

Arguments

`object`	An object of class `emmGrid`
`transform`	Character, list, or logical value. If `"response"`, `"mu"`, or `TRUE`, 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 `"none"` or `FALSE`, `object` is re-gridded so that its `bhat` slot contains `predict(object)` and its `linfct` slot is the identity. Any internal transformation information is preserved. If `transform = "pass"`, the object is not re-gridded in any way (this may be useful in conjunction with `N.sim`). If `transform` is a character value in `links` (which is the set of valid arguments for the `make.link` function, excepting `"identity"`), or if `transform` is a list of the same form as returned by `make.links` or `make.tran`, the results are formulated as if the response had been transformed with that link function.
`inv.link.lbl`	Character value. This applies only when `transform` is in `links`, 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 to use by default by `summary.emmGrid` (see `update.emmGrid`). This may be useful if, for example, when one specifies `transform = "log"` but desires summaries to be produced by default on the response scale.
`bias.adjust`	Logical value for whether to adjust for bias in back-transforming (`transform = "response"`). This requires a value of `sigma` to exist in the object or be specified.
`sigma`	Error SD assumed for bias correction (when `transform = "response"` and a transformation is in effect). If not specified, `object@misc$sigma` is used, and an error is thrown if it is not found.
`N.sim`	Integer value. If specified and `object` is based on a frequentist model (i.e., does not have a posterior sample), then a fake posterior sample is generated using the function `sim`.
`sim`	A function of three arguments (no names are assumed). If `N.sim` is supplied with a frequentist model, this function is called with respective arguments `N.sim`, `object@bhat`, and `object@V`. The default is the multivariate normal distribution.
`...`	Ignored.

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.

This function may also be used to simulate a sample of regression coefficients for a frequentist model for subsequent use as though it were a Bayesian model. To do so, specify a value for N.sim and a sample is simulated using the function sim. The grid may be further processed in accordance with the other arguments; or if transform = "pass", it is simply returned with the only change being the addition of the simulated sample.

Value

An emmGrid object with the requested changes

Degrees of freedom

In cases where the degrees of freedom depended on the linear function being estimated (e.g., Satterthwaite method), 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. An annotation is displayed below any subsequent summary results stating that the degrees-of-freedom method is inherited from the previous method at the time of re-gridding.

Note

Another way to use regrid is to supply a transform argument to ref_grid (either directly of indirectly via emmeans). This is often a simpler approach if the reference grid has not already been constructed.

Examples

pigs.lm <- lm(log(conc) ~ source + factor(percent), data = pigs)
rg <- ref_grid(pigs.lm)

# This will yield EMMs as GEOMETRIC means of concentrations:
(emm1 <- emmeans(rg, "source", type = "response"))
pairs(emm1) ## We obtain RATIOS

# This will yield EMMs as ARITHMETIC means of concentrations:
(emm2 <- emmeans(regrid(rg, transform = "response"), "source"))
pairs(emm2)  ## We obtain DIFFERENCES
# Same result, useful if we hadn't already created 'rg'
# emm2 <- emmeans(pigs.lm, "source", transform = "response")

# Simulate a sample of regression coefficients
set.seed(2.71828)
rgb <- regrid(rg, N.sim = 200, transform = "pass")
emmeans(rgb, "source", type = "response")  ## similar to emm1

emmeans

Estimated Marginal Means, aka Least-Squares Means

v1.6.0

GPL-2 | GPL-3

Authors

Russell V. Lenth [aut, cre, cph], Paul Buerkner [ctb], Maxime Herve [ctb], Jonathon Love [ctb], Hannes Riebl [ctb], Henrik Singmann [ctb]

Initial release

2021-04-25