1\name{powerlink}
2\alias{powerlink}
3%- Also NEED an '\alias' for EACH other topic documented here.
4\title{ Power Link Function }
5\description{
6  Computes the power transformation, including its inverse and the
7  first two derivatives.
8
9}
10\usage{
11powerlink(theta, power = 1, inverse = FALSE, deriv = 0,
12          short = TRUE, tag = FALSE)
13}
14%- maybe also 'usage' for other objects documented here.
15\arguments{
16  \item{theta}{
17  Numeric or character.
18  See below for further details.
19
20  }
21  \item{power}{
22  This denotes the power or exponent.
23
24
25  }
26
27  \item{inverse, deriv, short, tag}{
28  Details at \code{\link{Links}}.
29
30
31  }
32
33}
34\details{
35  The power link function raises a parameter by a certain value of
36  \code{power}.
37  Care is needed because it is very easy to get numerical
38  problems, e.g., if \code{power=0.5} and \code{theta} is
39  negative.
40
41
42
43}
44\value{
45  For \code{powerlink} with \code{deriv = 0}, then \code{theta} raised
46  to the power of \code{power}.
47  And if \code{inverse = TRUE} then
48  \code{theta} raised to the power of \code{1/power}.
49
50
51  For \code{deriv = 1}, then the function returns
52  \emph{d} \code{theta} / \emph{d} \code{eta} as a function of \code{theta}
53  if \code{inverse = FALSE},
54  else if \code{inverse = TRUE} then it returns the reciprocal.
55
56
57}
58%\references{
59%  McCullagh, P. and Nelder, J. A. (1989).
60%  \emph{Generalized Linear Models}, 2nd ed. London: Chapman & Hall.
61%
62%}
63\author{ Thomas W. Yee }
64
65\note{
66  Numerical problems may occur for certain combinations of
67  \code{theta} and \code{power}.
68  Consequently this link function should be used with caution.
69
70
71}
72
73\seealso{
74  \code{\link{Links}},
75  \code{\link{loglink}}.
76
77
78}
79\examples{
80powerlink("a", power = 2, short = FALSE, tag = TRUE)
81powerlink(x <- 1:5)
82powerlink(x, power = 2)
83max(abs(powerlink(powerlink(x, power = 2),
84                  power = 2, inverse = TRUE) - x))  # Should be 0
85powerlink(x <- (-5):5, power = 0.5)  # Has NAs
86
87# 1/2 = 0.5
88pdata <- data.frame(y = rbeta(n = 1000, shape1 = 2^2, shape2 = 3^2))
89fit <- vglm(y ~ 1, betaR(lshape1 = powerlink(power = 0.5), i1 = 3,
90                         lshape2 = powerlink(power = 0.5), i2 = 7), data = pdata)
91t(coef(fit, matrix = TRUE))
92Coef(fit)  # Useful for intercept-only models
93vcov(fit, untransform = TRUE)
94}
95\keyword{math}
96\keyword{models}
97\keyword{regression}
98
99