% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/predict.nestedLogit.R
\name{predict.nestedLogit}
\alias{predict.nestedLogit}
\alias{fitted.nestedLogit}
\alias{print.predictNestedLogit}
\alias{confint.predictNestedLogit}
\alias{print.predictDichotomies}
\title{Predicted Probabilities and Logits for \code{"nestedLogit"} Models}
\usage{
\method{predict}{nestedLogit}(object, newdata, model = c("nested", "dichotomies"), ...)

\method{print}{predictNestedLogit}(x, n = min(10L, nrow(x$p)), ...)

\method{confint}{predictNestedLogit}(
  object,
  parm = c("prob", "logit"),
  level = 0.95,
  conf.limits.logit = TRUE,
  ...
)

\method{print}{predictDichotomies}(x, n = 10L, ...)

\method{fitted}{nestedLogit}(object, model = c("nested", "dichotomies"), ...)
}
\arguments{
\item{object}{a fitted object of class \code{"nestedLogit"};
for \code{confint}, an object of class \code{"predictNestedLogit"}.}

\item{newdata}{a data frame containing combinations of values of the predictors
at which fitted probabilities (or other quantities) are to be computed.
If missing, the original data are used.}

\item{model}{either \code{"nested"} (the default), in which case fitted probabilities
under the nested logit model are returned, or \code{"dichotomies"}, in which case
\code{\link{predict.glm}} is invoked for each binary logit model fit to the nested
dichotomies and a named list of the results is returned.}

\item{\dots}{arguments to be passed down.}

\item{x}{an object of class \code{"predictNestedLogit"} or \code{"predictDichotomies"}.}

\item{n}{an integer or \code{"all"} to control how many rows are printed for each of the
predicted values.}

\item{parm}{one of \code{"prob"} or \code{"logit"},
indicating whether to generate confidence intervals for probabilities or logits
of the responses.}

\item{level}{confidence level, a number between 0 and 1; default is \code{0.95}.}

\item{conf.limits.logit}{logical; when \code{parm = "prob"}, if \code{TRUE} (the default),
confidence limits are computed on the logit scale and back-transformed to probabilities;
if \code{FALSE}, Wald-type limits are computed directly on the probability scale.}
}
\value{
\itemize{
\item The \code{predict} and \code{fitted} methods return an object of class \code{"predictNestedLogit"}
(when \code{model = "nested"}) or \code{"predictDichotomies"} (when \code{model = "dichotomies"}).

A \code{"predictNestedLogit"} object is a list containing:
\describe{
\item{\code{p}}{a data frame of predicted probabilities, with one column per response category.}
\item{\code{logit}}{a data frame of predicted logits.}
\item{\code{se.p}}{a data frame of standard errors of predicted probabilities.}
\item{\code{se.logit}}{a data frame of standard errors of predicted logits.}
\item{\code{.data}}{the \code{newdata} data frame, if supplied.}
}

A \code{"predictDichotomies"} object is a named list of data frames, one per dichotomy,
each produced by \code{\link{predict.glm}}.

\item The \code{confint} method returns a data frame of point estimates and confidence limits.
\item The various \code{print} methods invisibly return their \code{x} arguments.
}
}
\description{
The \code{predict} and \code{fitted} methods compute predicted values from a fitted
\code{"nestedLogit"} model.
The \code{confint} method computes point-wise confidence limits for predicted response-category
probabilities or logits.

\describe{
\item{\code{predict}, \code{fitted}}{Compute predicted response-category probabilities
(or predicted logits for each binary logit model in the dichotomies) from a fitted
\code{"nestedLogit"} model.}
\item{\code{confint}}{Compute point-wise confidence limits for predicted response-category
probabilities or logits.}
\item{\code{print} methods}{Print predicted probabilities, logits, and their standard errors,
with control over how many rows to display.}
}
}
\details{
The \code{predict} method provides predicted values for two representations of the model.
\code{model = "nested"} (the default) gives the fitted probabilities for each of the response categories,
along with the corresponding logits and standard errors of each.
\code{model = "dichotomies"} gives the fitted log odds for each of the binary logit models in the
nested dichotomies.

The \code{fitted} method (with no \code{newdata}) is equivalent to \code{predict} applied to the
original data used to fit the model.

For the \code{confint} method with \code{parm = "prob"}, setting
\code{conf.limits.logit = TRUE} (the default) computes confidence limits on the logit scale
and back-transforms them to probabilities, which ensures that the limits lie in \eqn{[0, 1]}.
Setting \code{conf.limits.logit = FALSE} computes Wald-type confidence intervals directly on the
probability scale, which may extend outside \eqn{[0, 1]}.
}
\examples{
# define continuation dichotomies for level of education
cont.dichots <- continuationLogits(c("<highschool",
                                     "highschool",
                                     "college",
                                     "graduate"))

# fit a nested model for the GSS data
m <- nestedLogit(degree ~ parentdeg + year,
                 cont.dichots,
                 data=GSS)

# predicted probabilities for first few cases
predict(m)

# predicted probabilities at specific values of predictors
new <- expand.grid(parentdeg=c("<highschool",  "highschool",
                               "college", "graduate"),
                   year=c(1972, 2016))

fit <- predict(m, newdata=new)
cbind(new, fit)

# use fitted() -- equivalent to predict() on the original data
f <- fitted(m)

# predicted logits for each dichotomy
pred.dichot <- predict(m, newdata=new, model="dichotomies")
pred.dichot

# confidence intervals for predicted probabilities
fit.ci <- confint(fit)
head(fit.ci)

# confidence intervals for predicted logits
fit.ci.logit <- confint(fit, parm="logit")
head(fit.ci.logit)
}
\seealso{
\code{\link{nestedLogit}}, \code{\link{nestedMethods}},
\code{\link{plot.nestedLogit}},
\code{\link{as.data.frame.predictNestedLogit}}
}
\author{
John Fox and Michael Friendly
}
\keyword{regression}
