% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/effects.r
\name{powerTrans}
\alias{powerTrans}
\title{Power Transformation}
\usage{
powerTrans(
  y,
  eps = 0.001,
  target = NULL,
  interp = FALSE,
  forceYJ = FALSE,
  useStDev = FALSE
)
}
\arguments{
\item{y}{A vector of values to use.}

\item{eps}{Tolerance for lambda = 0.}

\item{target}{The value to target in the distribution.  (If null, the first value
in the vector is used.)  This will be moved to the first value in results.}

\item{interp}{Logical value for whether to spline interpolate lambda 
(ideal for vectors of small length).  This will default if the number
of values is less than 100, as in \link[MASS]{boxcox}.}

\item{forceYJ}{A logical value whether to force a Yeo-Johnson transformation for non-negative
values.  Negative values trigger
the transformation, but positive values can be transformed similarly.}

\item{useStDev}{A logical value whether to initially use standard deviates of y.
This might be useful if the range of y is restricted, say between 0 and 1.}
}
\value{
A list containing the following:
\item{opt.lambda}{The optimized lambda parameter.}
\item{transformed}{The power-transformed values.}
\item{lambda}{If spline interpolation is used, the values of lambda used.}
\item{loglik}{If spline interpolation is used, the log-liklihoods calculated for lambda.}
}
\description{
A function that transforms a vector of statistics or data to be 
approximately normally distributed.
}
\details{
This function uses a Box-Cox power transformation for a vector of values,
(presumably statistics from RRPP) with the following conditions:

(1) If any values are 0 or negative, a Yeo-Johnson transformation is performed
to optimize lambda with only positive values.

(2) The lambda parameter is optimized over a range of -2 to +2,
as is typical for most applications.

(3) The first (or targeted) value (assumed to be the observed value in a 
distribution of random values) is removed from the vector to 
perform optimization of lambda, but is returned to the vector for
transformation.  This assures that large, aberrant values, such
as might be found via RRPP for large effects, do not have 
leverage for the optimization.

A Yeo-Johnson transformation can be forced, which for positive values
merely shifts the distribution by adding 1.  For most RRPP statistics
(SS. MS, Rsq, F, d), this is not needed for effect sizes, as values are positive.  
However, for log-likelihoods, this might be a good idea for comparisons, 
because values might be strongly positive or strongly negative.

Using standard deviates (useStDev) is a good idea for statistics with
aberrant ranges (like 0 to 1, or 1,000 to 2,000).  If used, a Yeo-Johnson
transformation is implicit, since standardizing introduces negative values.
}
\references{
Box, G. E. P. and Cox, D. R. (1964) An analysis of transformations 
(with discussion). Journal of the Royal Statistical Society B, 26, 211–252.

Yeo, I. and Johnson, R. (2000) A new family of power transformations 
to improve normality or symmetry. Biometrika, 87, 954-959.
}
\author{
Michael Collyer
}
\keyword{utilities}
