1\name{lrt.stat}
2\alias{lrt.stat}
3\alias{lrt.stat.vlm}
4%- Also NEED an '\alias' for EACH other topic documented here.
5\title{ Likelihood Ratio Test
6  Statistics Evaluated at the Null Values }
7
8\description{
9  Generic function that computes
10  likelihood ratio test (LRT)
11  statistics evaluated at the null values
12  (consequently they do not suffer from the Hauck-Donner effect).
13
14
15}
16\usage{
17lrt.stat(object, ...)
18lrt.stat.vlm(object, values0 = 0, subset = NULL, omit1s = TRUE,
19          all.out = FALSE, trace = FALSE, ...)
20}
21%- maybe also 'usage' for other objects documented here.
22\arguments{
23\item{object, values0, subset}{
24  Same as in \code{\link{wald.stat.vlm}}.
25
26
27}
28\item{omit1s, all.out, trace}{
29  Same as in \code{\link{wald.stat.vlm}}.
30
31
32}
33\item{\dots}{
34  Ignored for now.
35
36
37}
38}
39\details{
40   When \code{summary()} is applied to a \code{\link{vglm}} object
41  a 4-column Wald table is produced.
42  The corresponding p-values are generally viewed as inferior to
43  those from a likelihood ratio test (LRT).
44  For example, the Hauck and Donner (1977) effect (HDE) produces
45  p-values that are biased upwards (see \code{\link{hdeff}}).
46  Other reasons are that the Wald test is often less accurate
47  (especially in small samples) and is not invariant to
48  parameterization.
49  By default, this function returns p-values based on the LRT by
50  deleting one column at a time from the big VLM matrix
51  and then restarting IRLS to obtain convergence (hopefully).
52  Twice the difference between the log-likelihoods
53  (or equivalently, the difference in the deviances if they are defined)
54  is asymptotically chi-squared with 1 degree of freedom.
55  One might expect the p-values from this function
56  therefore to be more accurate
57  and not suffer from the HDE.
58  Thus this function is a recommended
59  alternative (if it works) to \code{\link{summaryvglm}}
60  for testing for the significance of a regression coefficient.
61
62
63
64}
65\value{
66  By default, a vector of signed square root of the LRT statistics;
67  these are asymptotically standard normal under the null hypotheses.
68  If \code{all.out = TRUE} then a list is returned with the
69  following components:
70  \code{lrt.stat} the signed LRT statistics,
71  \code{pvalues} the 2-sided p-values,
72  \code{Lrt.stat2} the usual LRT statistic,
73  \code{values0} the null values.
74
75
76
77%  and some other are detailed in \code{\link{wald.stat.vlm}}
78
79
80
81
82
83% By default, a vector of (2-sided test) p-values.
84% If the model is intercept-only  then a \code{NULL} is returned
85% by default.
86% If \code{lrt.stat = TRUE} then a 2-column matrix is returned
87% comprising of p-values and LRT statistics.
88
89
90
91}
92%\references{
93%}
94\author{ T. W. Yee.  }
95
96\section{Warning }{
97  See \code{\link{wald.stat.vlm}}.
98
99
100}
101
102%\note{
103%  Only models with a full-likelihood are handled,
104%  so that quasi-type models such as \code{\link{quasipoissonff}}
105%  should not be fed in.
106
107
108
109%% One day this function might allow for terms,
110%% such as arising from \code{\link[stats]{poly}}
111%% and \code{\link[splines]{bs}}.
112
113
114%% i.e., some of the columns are grouped together,
115
116%}
117\seealso{
118  \code{\link{score.stat}},
119  \code{\link{wald.stat}},
120  \code{\link{summaryvglm}},
121  \code{\link{anova.vglm}},
122  \code{\link{vglm}},
123  \code{\link{lrtest}},
124  \code{\link{confintvglm}},
125  \code{\link[stats]{pchisq}},
126  \code{\link{profilevglm}},
127  \code{\link{hdeff}}.
128
129
130%  \code{\link[stats]{profile}},
131%  \code{\link[MASS]{profile.glm}},
132%  \code{\link[MASS]{plot.profile}}.
133
134
135% \code{\link{multinomial}},
136% \code{\link{cumulative}},
137
138
139
140}
141
142\examples{
143set.seed(1)
144pneumo <- transform(pneumo, let = log(exposure.time),
145                            x3 = rnorm(nrow(pneumo)))
146fit <- vglm(cbind(normal, mild, severe) ~ let, propodds, pneumo)
147cbind(coef(summary(fit)),
148      "signed LRT stat" = lrt.stat(fit, omit1s = FALSE))
149summary(fit, lrt0 = TRUE)  # Easy way to get it
150}
151
152
153% Add one or more standard keywords, see file 'KEYWORDS' in the
154% R documentation directory.
155\keyword{models}
156\keyword{regression}
157
158
159
160
161