R: Response-transformation extensions

make.tran {emmeans} | R Documentation

## Response-transformation extensions

### Description

The `make.tran` function creates the needed information to perform transformations of the response variable, including inverting the transformation and estimating variances of back-transformed predictions via the delta method. `make.tran` is similar to `make.link`, but it covers additional transformations. The result can be used as an environment in which the model is fitted, or as the `tran` argument in `update.emmGrid` (when the given transformation was already applied in an existing model).

### Usage

    make.tran(type = c("genlog", "power", "boxcox", "sympower", "asin.sqrt"),
      param = 1)

### Arguments

`type` | The name of the transformation. See Details.
`param` | Numeric parameter needed for the transformation. Optionally, it may be a vector of two numeric values; the second element specifies an alternative base or origin for certain transformations. See Details.

### Details

The functions `emmeans`, `ref_grid`, and related ones automatically detect response transformations that are recognized by examining the model formula. These are `log`, `log2`, `log10`, `sqrt`, `logit`, `probit`, `cauchit`, `cloglog`; as well as (for a response variable `y`) `asin(sqrt(y))`, `asinh(sqrt(y))`, and `sqrt(y) + sqrt(y+1)`. In addition, any constant multiple of these (e.g., `2*sqrt(y)`) is auto-detected and appropriately scaled (see also the `tran.mult` argument in `update.emmGrid`).

A few additional character strings may be supplied as the `tran` argument in `update.emmGrid`: `"identity"`, `"1/mu^2"`, `"inverse"`, `"reciprocal"`, `"asin.sqrt"`, and `"asinh.sqrt"`.

More general transformations may be provided as a list of functions and supplied as the `tran` argument as documented in `update.emmGrid`. The `make.tran` function returns a suitable list of functions for several popular transformations. Besides being usable with `update`, the user may use this list as an enclosing environment in fitting the model itself, in which case the transformation is auto-detected when the special name `linkfun` (the transformation itself) is used as the response transformation in the call. See the examples below.

Most of the transformations available in "make.tran" require a parameter, specified in `param`; in the following discussion, we use p to denote this parameter, and y to denote the response variable. The `type` argument specifies the following transformations:

`"genlog"`

  Generalized logarithmic transformation: log(y + p), where y > -p

`"power"`

  Power transformation: y^p, where y > 0. When p = 0, `"log"` is used instead

`"boxcox"`

  The Box-Cox transformation (unscaled by the geometric mean): (y^p - 1) / p, where y > 0. When p = 0, log(y) is used.

`"sympower"`

  A symmetrized power transformation on the whole real line: abs(y)^p * sign(y). There are no restrictions on y, but we require p > 0 in order for the transformation to be monotone and continuous.

`"asin.sqrt"`

  Arcsin-square-root transformation: sin^(-1)(y/p)^{1/2)}. Typically, the parameter p is equal to 1 for a fraction, or 100 for a percentage.

The user may include a second element in `param` to specify an alternative origin (other than zero) for the `"power"`, `"boxcox"`, or `"sympower"` transformations. For example, type = "power", param = c(1.5, 4) specifies the transformation (y - 4)^1.5. In the `"genpower"` transformation, a second `param` element may be used to specify a base other than the default natural logarithm. For example, type = "genlog", param = c(.5, 10) specifies the log10(y + .5) transformation.

For purposes of back-transformation, the sqrt(y) + sqrt(y+1) transformation is treated exactly the same way as 2*sqrt(y), because both are regarded as estimates of 2√μ.

### Value

A `list` having at least the same elements as those returned by `make.link`. The `linkfun` component is the transformation itself.

### Note

We modify certain `make.link` results in transformations where there is a restriction on valid prediction values, so that reasonable inverse predictions are obtained, no matter what. For example, if a `sqrt` transformation was used but a predicted value is negative, the inverse transformation is zero rather than the square of the prediction. A side effect of this is that it is possible for one or both confidence limits, or even a standard error, to be zero.

### Examples

    # Fit a model using an oddball transformation:
    bctran <- make.tran("boxcox", 0.368)
    warp.bc <- with(bctran,
        lm(linkfun(breaks) ~ wool * tension, data = warpbreaks))
    # Obtain back-transformed LS means:
    emmeans(warp.bc, ~ tension | wool, type = "response")

    ## Not run:
    # An existing model 'mod' was fitted with a log(y + 1) transformation...
    mod.rg <- update(ref_grid(mod), tran = make.tran("genlog", 1))
    emmeans(mod.rg, "treatment")

    ## End(Not run)

[Package emmeans version 1.1.3 Index]