Learn R Programming

emmeans (version 1.6.2-1)

make.tran: 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",
  "bcnPower", "scale"), param = 1, y, ...)

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.

y, ...

Used only with type = "scale". These parameters are passed to scale to determine param.

Value

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

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, log1p, 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", "log10", "log2", "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.

"bcnPower"

Box-Cox with negatives allowed, as described for the bcnPower function in the car package. It is defined as the Box-Cox transformation \((z^p - 1) / p\) of the variable \(z = y + (y^2+g^2)^(1/2)\). This requires param to have two elements: the power \(p\) and the offset \(g > 0\).

"scale"

This one is a little different than the others, in that param is ignored; instead, param is determined by calling scale(y, ...). The user should give as y the response variable in the model to be fitted to its scaled version.

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. In the "bcnPower" transformation, the second element is required and must be positive.

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\sqrt\mu\).

Examples

Run this code
# NOT RUN {
# 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")

### Using a scaled response...
# Case where it is auto-detected:
fib.lm <- lm(scale(strength) ~ diameter + machine, data = fiber)
ref_grid(fib.lm) 

# Case where scaling is not auto-detected -- and what to do about it:
fib.aov <- aov(scale(strength) ~ diameter + Error(machine), data = fiber)
fib.rg <- suppressWarnings(ref_grid(fib.aov, at = list(diameter = c(20, 30))))

# Scaling was not retrieved, so we can do:
fib.rg = update(fib.rg, tran = make.tran("scale", y = fiber$strength))
emmeans(fib.rg, "diameter")

# }
# NOT RUN {
### An existing model 'mod' was fitted with a y^(2/3) transformation...
  ptran = make.tran("power", 2/3)
  emmeans(mod, "treatment", tran = ptran)
# }

Run the code above in your browser using DataLab