% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.nested-ci.R
\name{plot.nestedLogit}
\alias{plot.nestedLogit}
\title{Plotting Nested Logit Models}
\usage{
\method{plot}{nestedLogit}(
  x,
  x.var,
  others,
  n.x.values = 100L,
  scale = c("prob", "logit"),
  xlab = x.var,
  ylab = NULL,
  main,
  cex.main = 1,
  digits.main = getOption("digits") - 2L,
  font.main = 1L,
  pch = 1L:length(response.levels),
  lwd = 3,
  lty = 1L:length(response.levels),
  col = (scales::hue_pal())(length(response.levels)),
  legend = TRUE,
  legend.inset = 0.01,
  legend.location = "topleft",
  legend.bty = "n",
  conf.level = 0.95,
  conf.alpha = 0.25,
  label = FALSE,
  label.x = "max",
  label.cex = 1.25,
  label.col = col,
  ...
)
}
\arguments{
\item{x}{an object of \code{"nestedLogit"} produced by \code{\link{nestedLogit}}.}

\item{x.var}{quoted name of the variable to appear on the x-axis; if omitted, the first
predictor in the model is used.}

\item{others}{a named list of values for the other variables in the model,
that is, other than \code{x.var}; if any other predictor is omitted, it is set
to an arbitrary value---the mean for a numeric predictor or the first level or
value of a factor, character, or logical predictor; only one value may be
specified for each variable in \code{others}.}

\item{n.x.values}{the number of evenly spaced values of \code{x.var} at which
to evaluate fitted probabilities to be plotted (default \code{100}).}

\item{scale}{character string; \code{"prob"} (the default) plots fitted probabilities
on the y-axis; \code{"logit"} plots fitted log odds (logits), i.e., \eqn{\log(p/(1-p))}.}

\item{xlab}{label for the x-axis (defaults to the value of \code{x.var}).}

\item{ylab}{label for the y-axis (defaults to \code{"Fitted Probability"} when
\code{scale = "prob"} and \code{"Fitted Log Odds"} when \code{scale = "logit"}).}

\item{main}{main title for the graph (if missing, constructed from the variables and
values in \code{others}).}

\item{cex.main}{size of main title (see \code{\link{par}}).}

\item{digits.main}{number of digits to retain when rounding values for the main title.}

\item{font.main}{font for main title (see \code{\link{par}}).}

\item{pch}{plotting characters (see \code{\link{par}}).}

\item{lwd}{line width (see \code{\link{par}}).}

\item{lty}{line types (see \code{\link{par}}).}

\item{col}{line colors for the response levels (see \code{\link{par}}).}

\item{legend}{if \code{TRUE} (the default), add a legend for the
response levels to the graph. Ignored when \code{label = TRUE}.}

\item{legend.inset}{default \code{0.01} (see \code{\link{legend}}).}

\item{legend.location}{position of the legend (default \code{"topleft"},
see \code{\link{legend}}).}

\item{legend.bty}{the type of box to be drawn around the legend. The allowed values are "o" (the default) and "n".}

\item{conf.level}{the level for pointwise confidence envelopes around the predicted values;
the default is \code{0.95}. If \code{NULL}, the confidence envelopes are suppressed.}

\item{conf.alpha}{the opacity of the confidence envelopes; the default is \code{0.3}.}

\item{label}{if \code{TRUE}, label the curves directly instead of using a legend.
Default is \code{FALSE}.}

\item{label.x}{where to place the label for each curve. Either a single string,
\code{"min"} or \code{"max"} (applied to all curves), or a character vector of
length equal to the number of response categories with each element being
\code{"min"} or \code{"max"}, e.g. \code{label.x = c("min", "max", "max")}.
\code{"min"} places the label at the left end of the curve;
\code{"max"} (the default) places it at the right end.}

\item{label.cex}{character expansion factor for direct labels; default \code{1.25}.}

\item{label.col}{colors for direct labels; defaults to \code{col}, so labels match
their curves. Supply a vector of length equal to the number of response
categories to use different colors for the labels.}

\item{\dots}{arguments to be passed to \code{\link{matplot}}.}
}
\value{
NULL Used for its side-effect of producing a plot
}
\description{
A \code{\link{plot}} method for \code{"nestedLogit"} objects produced by the
\code{\link{nestedLogit}} function. Fitted probabilities under the model,
or the corresponding logits are plotted
for each level of the polytomous response variable, with one of the explanatory variables
on the horizontal axis and other explanatory variables fixed to particular values.
By default, a 95\% pointwise confidence envelope is added to the plot.
}
\examples{
data("Womenlf", package = "carData")
m <- nestedLogit(partic ~ hincome + children,
                 logits(work=dichotomy("not.work", c("parttime", "fulltime")),
                        full=dichotomy("parttime", "fulltime")),
                        data=Womenlf)
plot(m, legend.location="top")

op <- par(mfcol=c(1, 2), mar=c(4, 4, 3, 1) + 0.1)
plot(m, "hincome", list(children="absent"),
     xlab="Husband's Income", legend=FALSE)
plot(m, "hincome", list(children="present"),
     xlab="Husband's Income")
par(op)

# Plot on the logit (log-odds) scale
plot(m, "hincome", list(children="absent"), scale = "logit",
     xlab = "Husband's Income")

# Gators example: direct curve labels instead of a legend
data("gators", package = "nestedLogit")
gators.nested <- nestedLogit(food ~ length,
  logits(d1 = dichotomy("Other", c("Fish", "Invertebrates")),
         d2 = dichotomy("Fish", "Invertebrates")),
  data = gators)

# All labels at the right end (default)
plot(gators.nested, x.var = "length", label = TRUE,
     xlab = "Alligator length (m)")

# Mixed placement: Other and Invertebrates labeled at left, Fish at right
# (food levels are: "Other", "Fish", "Invertebrates")
plot(gators.nested, x.var = "length", label = TRUE,
     label.x = c("min", "max", "min"),
     xlab = "Alligator length (m)")

}
\seealso{
\code{\link{nestedLogit}}, \code{\link[graphics]{matplot}}
}
\author{
John Fox, Michael Friendly
}
