1\name{score.stat}
2\alias{score.stat}
3\alias{score.stat.vlm}
4%- Also NEED an '\alias' for EACH other topic documented here.
5\title{ Rao's Score Test
6  Statistics Evaluated at the Null Values }
7\description{
8  Generic function that computes
9  Rao's score test statistics evaluated at the null values.
10}
11%  (consequently they
12%  may
13%  not suffer from the Hauck-Donner effect).
14\usage{
15score.stat(object, ...)
16score.stat.vlm(object, values0 = 0, subset = NULL, omit1s = TRUE,
17          all.out = FALSE, orig.SE = FALSE, iterate.SE = TRUE,
18          iterate.score = TRUE, trace = FALSE, ...)
19}
20%- maybe also 'usage' for other objects documented here.
21\arguments{
22\item{object, values0, subset}{
23  Same as in \code{\link{wald.stat.vlm}}.
24
25
26}
27\item{omit1s, all.out}{
28  Same as in \code{\link{wald.stat.vlm}}.
29
30
31}
32\item{orig.SE, iterate.SE}{
33  Same as in \code{\link{wald.stat.vlm}}.
34
35
36}
37\item{iterate.score}{
38  Logical. The score vector is evaluated at one value of
39  \code{values0} and at other regression coefficient values.
40  These other values may be either the MLE obtained from the original
41  object (\code{FALSE}), else at values obtained by
42  further IRLS iterations---this argument enables that choice.
43
44
45
46}
47\item{trace}{
48  Same as in \code{\link{wald.stat.vlm}}.
49
50
51}
52\item{\dots}{
53  Ignored for now.
54
55
56}
57}
58\details{
59  The (Rao) \emph{score test}
60  (also known as the \emph{Lagrange multiplier test} in econometrics)
61  is a third general method for
62  hypothesis testing under a likelihood-based framework
63  (the others are the likelihood ratio test and
64  Wald test; see \code{\link{lrt.stat}} and
65  \code{\link{wald.stat}}).
66  Asymptotically, the three tests are equivalent.
67  The Wald test is not invariant to parameterization, and
68  the usual Wald test statistics computed at the estimates
69  make it vulnerable to the Hauck-Donner effect
70  (HDE; see \code{\link{hdeff}}).
71  This function is similar to \code{\link{wald.stat}} in that
72  one coefficient is set to 0 (by default) and the \emph{other}
73  coefficients are iterated by IRLS to get their MLE subject to this
74  constraint.
75  The SE is almost always based on the expected information matrix
76  (EIM) rather than the OIM, and for some models
77  the EIM and OIM coincide.
78
79
80
81%  It is not permissible to have \code{iterate.SE = TRUE}
82%  and \code{orig.SE = TRUE} together.
83
84
85
86
87}
88\value{
89  By default the
90  signed square root of the
91  Rao score statistics are returned.
92  If \code{all.out = TRUE} then a list is returned with the
93  following components:
94  \code{score.stat} the score statistic,
95  \code{SE0} the standard error of that coefficient,
96  \code{values0} the null values.
97  Approximately, the default score statistics output are
98  standard normal random variates if each null hypothesis is true.
99
100
101
102  Altogether,
103  by the eight combinations of \code{iterate.SE}, \code{iterate.score}
104  and \code{orig.SE},
105  there are six different variants of the Rao score statistic
106  that can be returned because the score vector has 2 and
107  the SEs have 3 subvariants.
108
109
110
111}
112%\references{
113%
114%}
115\author{ Thomas W. Yee }
116
117%\note{
118%}
119
120\section{Warning }{
121  See \code{\link{wald.stat.vlm}}.
122
123
124}
125
126
127\seealso{
128  \code{\link{wald.stat}},
129  \code{\link{lrt.stat}},
130  \code{\link{summaryvglm}},
131  \code{\link[stats]{summary.glm}},
132  \code{\link{anova.vglm}},
133  \code{\link{vglm}},
134  \code{\link{hdeff}}.
135
136
137% \code{\link{anova.vglm}},
138
139
140
141}
142\examples{
143set.seed(1)
144pneumo <- transform(pneumo, let = log(exposure.time),
145                            x3 = rnorm(nrow(pneumo)))
146(pfit <- vglm(cbind(normal, mild, severe) ~ let + x3, propodds, pneumo))
147score.stat(pfit)  # No HDE here; should be similar to the next line:
148coef(summary(pfit))[, "z value"]  # Wald statistics computed at the MLE
149summary(pfit, score0 = TRUE)
150}
151\keyword{models}
152\keyword{regression}
153
154