powerTransform: Performs a combination of a linear and a power transformation on a variable. The transformed variable is stored in the `data.frame data`.

Description

Perform a combination of a linear and a power transformation on a variable whose name is given as a character string in var.name. The transformed variable is stored in the data.frame data. The name of the transformed variable is made by prepending to the original var.name a combination of (i) .offset, if offset is nonzero, (ii) neg., if scale is -1, or scaled., if abs(scale) is other than one, and (iii) either log., sqrt., recip. or power., if power is other than one. No action is taken if there is no transformation (i.e. offset = 0, scale = 1 and power = 1). Also, the titles list is extended to include a component with a generated title for the transformed variable with text indicating the transformation prepended to the title for the var.name obtained from the titles list. For nonzero offset, `Offset ' is prepended, For scaled not equal to one, the possible prepends are `Negative of ' and `Scaled '. The possible prepended texts for power not equal to one are `Logarithm of', `Square root of ', `Reciprocal of ' and `Power nnnn of ', where nnn is the power used.

Usage

powerTransform(var.name, power = 1, offset = 0, scale = 1, titles = NULL, data)

Value

A list with a component named data that is the data.frame containing the transformed variable, a component named tvar.name that is a character string

that is the name of the transformed variable in data, and a component named

titles that extends the list supplied in the titles argument to include a generated title for the transformed title, the name of the new component being

tvar.name.

Arguments

var.name: A character string specifying the name of the variable in the data.frame data that is to be transformed.
power: A number specifying the power to be used in the transformation. If equal to 1, the default, no power transformation is applied. Otherwise, the variable is raised to the specified power, after scaling and applying any nonzero offset. If power = 0, the natural logarithm is used to transform the response; however, if the smallest value to be log-transformed is less than 1e-04, an error is generated. A log-transformation in this situation may be possible if a nonzero offset and/or a scale not equal to one is used.
offset: A number to be added to each value of the variable, after any scaling and before applying any power transformation.
scale: A number to multiply each value of the variable, before adding any offset and applying any power transformation.
titles: A character vector, each element of which is named for a variable in data and is a character string giving a title to use in output (e.g. tables and graphs) involving the variable. If titles are not supplied, the column name of the variable in data is used.
data: A data.frame containing the variable to be transformed and to which the transformed variable is to be appended.

Author

Chris Brien

Examples

Run this code

## set up a factor with labels
x.dat <- data.frame(y = c(14, 42, 120, 150))
 
## transform y to logarithms
trans <- powerTransform("y", power = 0, titles=list(y = "Length (cm)"), data = x.dat)
x.dat <- trans$data
tvar.name <- trans$tvar.name

## transform y to logarithms after multiplying by -1 and adding 1.
z.dat <- data.frame( y = c(-5.25, -4.29, -1.22, 0.05))
trans <- powerTransform("y", power = 0, scale = -1, offset = 1 ,
                        titles=list(y = "Potential"), data = z.dat)
z.dat <- trans$data
tvar.name <- trans$tvar.name