1\name{sc.studentt2}
2\alias{sc.studentt2}
3%- Also NEED an '\alias' for EACH other topic documented here.
4\title{ Scaled Student t Distribution with 2 df Family Function }
5\description{
6  Estimates the location and scale parameters of
7  a scaled Student t distribution with 2 degrees of freedom,
8  by maximum likelihood estimation.
9
10
11}
12\usage{
13sc.studentt2(percentile = 50, llocation = "identitylink", lscale = "loglink",
14             ilocation = NULL, iscale = NULL, imethod = 1, zero = "scale")
15}
16%- maybe also 'usage' for other objects documented here.
17\arguments{
18  \item{percentile}{
19  A numerical vector containing values between 0 and 100,
20  which are the quantiles and expectiles.
21  They will be returned as `fitted values'.
22
23
24  }
25  \item{llocation, lscale}{
26  See \code{\link{Links}} for more choices,
27  and \code{\link{CommonVGAMffArguments}}.
28
29
30  }
31  \item{ilocation, iscale, imethod, zero}{
32  See \code{\link{CommonVGAMffArguments}} for details.
33
34
35  }
36}
37\details{
38  Koenker (1993) solved for the distribution whose quantiles are
39  equal to its expectiles.
40  Its canonical form has mean and mode at 0,
41  and has a heavy tail (in fact, its variance is infinite).
42
43
44% This is called Koenker's distribution here.
45
46
47  The standard (``canonical'') form of this
48  distribution can be endowed with a location and scale parameter.
49  The standard form has a density
50  that can be written as
51  \deqn{f(z) = 2 / (4 + z^2)^{3/2}}{%
52        f(z) = 2 / (4 + z^2)^(3/2)
53  }
54  for real \eqn{y}.
55  Then \eqn{z = (y-a)/b} for location and scale parameters
56  \eqn{a} and \eqn{b > 0}.
57  The mean of \eqn{Y} is \eqn{a}{a}.
58  By default, \eqn{\eta_1=a)}{eta1=a} and
59  \eqn{\eta_2=\log(b)}{eta2=log(b)}.
60  The expectiles/quantiles corresponding to \code{percentile}
61  are returned as the fitted values;
62  in particular, \code{percentile = 50} corresponds to the mean
63  (0.5 expectile) and  median (0.5 quantile).
64
65
66  Note that if \eqn{Y} has a standard \code{\link{dsc.t2}}
67  then \eqn{Y = \sqrt{2} T_2}{Y = sqrt(2) * T_2} where \eqn{T_2}
68  has a Student-t distribution with 2 degrees of freedom.
69  The two parameters here can also be estimated using
70  \code{\link{studentt2}} by specifying \code{df = 2} and making
71  an adjustment for the scale parameter, however, this \pkg{VGAM}
72  family function is more efficient since the EIM is known
73  (Fisher scoring is implemented.)
74
75
76}
77\value{
78  An object of class \code{"vglmff"} (see \code{\link{vglmff-class}}).
79  The object is used by modelling functions such as \code{\link{vglm}},
80  \code{\link{rrvglm}}
81  and \code{\link{vgam}}.
82
83
84}
85\references{
86
87Koenker, R. (1993).
88When are expectiles percentiles? (solution)
89\emph{Econometric Theory},
90\bold{9}, 526--527.
91
92
93}
94\author{ T. W. Yee }
95%\note{
96%
97%}
98
99\seealso{
100  \code{\link{dsc.t2}},
101  \code{\link{studentt2}}.
102
103
104}
105\examples{
106set.seed(123); nn <- 1000
107kdata <- data.frame(x2 = sort(runif(nn)))
108kdata <- transform(kdata, mylocat = 1 + 3 * x2,
109                          myscale = 1)
110kdata <- transform(kdata, y = rsc.t2(nn, loc = mylocat, scale = myscale))
111fit  <- vglm(y ~ x2, sc.studentt2(perc = c(1, 50, 99)), data = kdata)
112fit2 <- vglm(y ~ x2,    studentt2(df = 2), data = kdata)  # 'same' as fit
113
114coef(fit, matrix = TRUE)
115head(fitted(fit))
116head(predict(fit))
117
118# Nice plot of the results
119\dontrun{ plot(y ~ x2, data = kdata, col = "blue", las = 1,
120     sub  = paste("n =", nn),
121     main = "Fitted quantiles/expectiles using the sc.studentt2() distribution")
122matplot(with(kdata, x2), fitted(fit), add = TRUE, type = "l", lwd = 3)
123legend("bottomright", lty = 1:3, lwd = 3, legend = colnames(fitted(fit)),
124       col = 1:3) }
125
126fit@extra$percentile  # Sample quantiles
127}
128\keyword{models}
129\keyword{regression}
130
131