\HeaderA{densityplot}{One-dimensional density plots for flow data}{densityplot}
\aliasA{densityplot,formula,flowSet-method}{densityplot}{densityplot,formula,flowSet.Rdash.method}
\aliasA{densityplot,formula,view-method}{densityplot}{densityplot,formula,view.Rdash.method}
\aliasA{densityplot,view,missing-method}{densityplot}{densityplot,view,missing.Rdash.method}
\aliasA{panel.densityplot.flowset}{densityplot}{panel.densityplot.flowset}
\aliasA{prepanel.densityplot.flowset}{densityplot}{prepanel.densityplot.flowset}
\keyword{methods}{densityplot}
\keyword{dplot}{densityplot}
\begin{Description}\relax
So far, density plots are only implemented for
\code{\LinkA{flowSet}{flowSet}}. The idea is to
horizontally stack plots of density estimates for all frames in the
\code{flowSet} for one or several flow parameters. In the latter case,
each parameter will be plotted in a separate panel, i.e., we
implicitely condition on parameters.
\end{Description}
\begin{Usage}
\begin{verbatim}

## method for 'flowSet' objects
## S4 method for signature 'formula, flowSet':
densityplot(
    x,
    data, 
    xlab,
    as.table=TRUE,
    overlap=0.3,
    prepanel=prepanel.densityplot.flowset,
    panel = panel.densityplot.flowset,
    filter=NULL,
    scales=list(y=list(draw=F)),
    channels,
    ...)

prepanel.densityplot.flowset(
    x,
    y,
    darg=list(n=50, na.rm=TRUE),
    frames, 
    overlap=0.3,
    subscripts,
    ...,
    which.channel)

panel.densityplot.flowset(
    x,
    y,
    darg=list(n=50, na.rm=TRUE),
    frames,
    channel,
    overlap = 0.3,
    channel.name,
    filter=NULL,
    fill=superpose.polygon$col,
    lty=superpose.polygon$lty,
    lwd=superpose.polygon$lwd,
    alpha=superpose.polygon$alpha,
    col=superpose.polygon$border,
    groups=NULL,
    refline=NULL,
    gpar,
    ...)


## methods for various workflow objects
## S4 method for signature 'formula, view':
densityplot(
    x,
    data,
    ...)

## S4 method for signature 'view, missing':
densityplot(
    x,
    data,
    channels,
    ...)

\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A formula describing the structure of the plot and the
variables to be used in the display. The structure of the formula is
\code{factor \textasciitilde{} parameter}, where \code{factor} can be any of the
phenotypic factors in the \code{phenoData} slot or an appropriate
factor object and \code{parameter} is a flow parameter. Panels for
multiple parameters are drawn if the formula structure is similar to
\code{factor \textasciitilde{} parameter1 + parameter2}, and \code{factor} can be
missing, in which case the sample names are used as y-variable. To
facilitate programatic access, the formula can be of special
structure \code{factor \textasciitilde{} .}, in which case the optional
\code{channel} argument is considered for parameter selection. For
the workflow methods, \code{x} can also be one of the several
workflow objects. 
\item[\code{data}] A \code{flowSet} object that serves as a source of data,
either a \code{\LinkA{flowFrame}{flowFrame}} or
\code{\LinkA{flowSet}{flowSet}}, or one of the several workflow
objects. 
\item[\code{xlab}] Label for data x axis, with suitable defaults taken from
the formula 
\item[\code{as.table, scales, darg}] These arguments are passed unchanged to
the corresponding methods in lattice, and are listed here only
because they provide different defaults.  See documentation for the
original methods for details. \code{darg} gets passed on to
\code{\LinkA{density}{density}}. 
\item[\code{overlap}] The amount of overlap between stacked density plots 
\item[\code{prepanel}] The prepanel function.  See
\code{\LinkA{xyplot}{xyplot}} 
\item[\code{panel}] the panel function.  See
\code{\LinkA{xyplot}{xyplot}} 
\item[\code{filter}] A \code{\LinkA{filter}{filter}},
\code{\LinkA{filterResult}{filterResult}} or
\code{\LinkA{filterResultList}{filterResultList}} object
or a list of such objects of the same length as the
\code{flowSet}. If applicable, the gate region will be superiposed
on the density curves using color shading. The software will figure
out whether the \code{filter} needs to be evaluated in order to be
plotted (in which case providing a \code{filterResult} can speed
things up considerably). 
\item[\code{channels}] A character vector of parameters that are supposed to
be plotted when the formula in \code{x} is of structure \code{factor
      \textasciitilde{} .}. 
\item[\code{subscripts, which.channel, channel.name, y}] Internal indices
necessary to map panels to parameters. 
\item[\code{frames}] An environment containing frame-specific data. 
\item[\code{channel}] The name of the currently plotted flow parameter. 
\item[\code{col, fill, lty, lwd, alpha}] Graphical parameters. These
mostly exist for conveniance and much more control is available
throught the \code{lattice}-like \code{par.setting} and
\code{flowViz.par.set} customization. The relevant parameter
category for density plots is \code{gate.density} with available
parameters \code{col, \bsl{}code\{fill\}, \bsl{}code\{lwd\} \bsl{}code\{alpha\} and
      \bsl{}code\{lty\}}. See \code{\LinkA{flowViz.par.set}{flowViz.par.set}} for details.
\item[\code{groups}] Use identical colors for grouping. The value of the
argument is expected to be a phenotypic variable in the
\code{flowSet}. 
\item[\code{refline}] Add one ore more vertical reference lines to the plot.
This argument is directly passed to
\code{\LinkA{panel.abline}{panel.abline}}. 
\item[\code{gpar}] A list of graphical parameters that are passed down to
the low level panel functions. This is for internal use only. The
public user interface to set graphical parameters is either
\code{par.settings} for customization of a single call or
\code{flowViz.par.set} for customization of session-wide defaults. 
\item[\code{...}] More arguments, usually passed on to the underlying
lattice methods. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Not all standard lattice arguments will have the intended
effect, but many should.  For a fuller description of possible
arguments and their effects, consult documentation on lattice (Trellis
docs would also work for the fundamentals).
\end{Details}
\begin{Section}{Methods}
\describe{

\item[densityplot] \code{signature(x = "formula", data =
        "flowSet")}: Creates density plots for one or several channels,
with samples stacked according to a \code{phenoData} variable.
Colors are used to indicate common values of this covariate
across panels. Filters can be added as the optional
\code{filter} arguments. See \code{\LinkA{xyplot}{xyplot}} for details. 


\item[densityplot] \code{signature(x = "formula", data = "view")}: A
method to create density plots for workspace
\code{\LinkA{view}{view}} objects. This still allows for some
level of customization, but most defaults will be set depending
on the input object. 

\item[densityplot] \code{signature(x = "view", data = "missing")}:
The default method for view objects. All defaults will be set. 

}
\end{Section}
\begin{Examples}
\begin{ExampleCode}

data(GvHD)
GvHD <- GvHD[pData(GvHD)$Patient %in% 6:7]

densityplot(~ `FSC-H`, GvHD)

densityplot(~ `FSC-H` + `SSC-H`, GvHD)

densityplot(~ ., GvHD[1:3])

## include a filter
densityplot(~ `FSC-H`, GvHD, filter=curv1Filter("FSC-H"))

\end{ExampleCode}
\end{Examples}

