\HeaderA{cdplot}{Conditional Density Plots}{cdplot}
\methaliasA{cdplot.default}{cdplot}{cdplot.default}
\methaliasA{cdplot.formula}{cdplot}{cdplot.formula}
\keyword{hplot}{cdplot}
\begin{Description}\relax
Computes and plots conditional densities describing how the
conditional distribution of a categorical variable \code{y} changes over a
numerical variable \code{x}.
\end{Description}
\begin{Usage}
\begin{verbatim}
cdplot(x, ...)

## Default S3 method:
cdplot(x, y,
  plot = TRUE, tol.ylab = 0.05, ylevels = NULL,
  bw = "nrd0", n = 512, from = NULL, to = NULL,
  col = NULL, border = 1, main = "", xlab = NULL, ylab = NULL,
  yaxlabels = NULL, xlim = NULL, ylim = c(0, 1), ...)

## S3 method for class 'formula':
cdplot(formula, data = list(),
  plot = TRUE, tol.ylab = 0.05, ylevels = NULL,
  bw = "nrd0", n = 512, from = NULL, to = NULL,
  col = NULL, border = 1, main = "", xlab = NULL, ylab = NULL,
  yaxlabels = NULL, xlim = NULL, ylim = c(0, 1), ...,
  subset = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an object, the default method expects either a single numerical variable.
\item[\code{y}] a \code{"factor"} interpreted to be the dependent variable
\item[\code{formula}] a \code{"formula"} of type \code{y \textasciitilde{} x} with a single dependent
\code{"factor"} and a single numerical explanatory variable.
\item[\code{data}] an optional data frame.
\item[\code{plot}] logical. Should the computed conditional densities be plotted?
\item[\code{tol.ylab}] convenience tolerance parameter for y-axis annotation.
If the distance between two labels drops under this threshold, they are
plotted equidistantly.
\item[\code{ylevels}] a character or numeric vector specifying in which order
the levels of the dependent variable should be plotted.
\item[\code{bw, n, from, to, ...}] arguments passed to \code{\LinkA{density}{density}}
\item[\code{col}] a vector of fill colors of the same length as \code{levels(y)}.
The default is to call \code{\LinkA{gray.colors}{gray.colors}}.
\item[\code{border}] border color of shaded polygons.
\item[\code{main, xlab, ylab}] character strings for annotation
\item[\code{yaxlabels}] character vector for annotation of y axis, defaults to
\code{levels(y)}.
\item[\code{xlim, ylim}] the range of x and y values with sensible defaults.
\item[\code{subset}] an optional vector specifying a subset of observations
to be used for plotting.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{cdplot} computes the conditional densities of \code{x} given
the levels of \code{y} weighted by the marginal distribution of \code{y}.
The densities are derived cumulatively over the levels of \code{y}.

This visualization technique is similar to spinograms (see \code{\LinkA{spineplot}{spineplot}})
and plots \eqn{P(y | x)}{} against \eqn{x}{}. The conditional probabilities
are not derived by discretization (as in the spinogram), but using a smoothing
approach via \code{\LinkA{density}{density}}.

Note, that the estimates of the conditional densities are more reliable for 
high-density regions of \eqn{x}{}. Conversely, the are less reliable in regions
with only few \eqn{x}{} observations.
\end{Details}
\begin{Value}
The conditional density functions (cumulative over the levels of \code{y})
are returned invisibly.
\end{Value}
\begin{Author}\relax
Achim Zeileis \email{Achim.Zeileis@R-project.org}
\end{Author}
\begin{References}\relax
Hofmann, H., Theus, M. (2005), \emph{Interactive graphics for visualizing
conditional distributions}, Unpublished Manuscript.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{spineplot}{spineplot}}, \code{\LinkA{density}{density}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## NASA space shuttle o-ring failures
fail <- factor(c(2, 2, 2, 2, 1, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 1,
                 1, 2, 1, 1, 1, 1, 1),
               levels = 1:2, labels = c("no", "yes"))
temperature <- c(53, 57, 58, 63, 66, 67, 67, 67, 68, 69, 70, 70,
                 70, 70, 72, 73, 75, 75, 76, 76, 78, 79, 81)

## CD plot
cdplot(fail ~ temperature)
cdplot(fail ~ temperature, bw = 2)
cdplot(fail ~ temperature, bw = "SJ")

## compare with spinogram
(spineplot(fail ~ temperature, breaks = 3))

## highlighting for failures
cdplot(fail ~ temperature, ylevels = 2:1)

## scatter plot with conditional density
cdens <- cdplot(fail ~ temperature, plot = FALSE)
plot(I(as.numeric(fail) - 1) ~ jitter(temperature, factor = 2),
     xlab = "Temperature", ylab = "Conditional failure probability")
lines(53:81, 1 - cdens[[1]](53:81), col = 2)
\end{ExampleCode}
\end{Examples}

