\HeaderA{lymphFilter-class}{Automated gating of elliptical cell populations in 2D.}{lymphFilter.Rdash.class}
\aliasA{lymphFilter}{lymphFilter-class}{lymphFilter}
\aliasA{lymphGate}{lymphFilter-class}{lymphGate}
\aliasA{\%in\%,flowFrame,lymphFilter-method}{lymphFilter-class}{.Rpcent.in.Rpcent.,flowFrame,lymphFilter.Rdash.method}
\keyword{misc}{lymphFilter-class}
\keyword{classes}{lymphFilter-class}
\begin{Description}\relax
Cell populations of roughly elliptical shape in two-dimensional projections
are of huge interest in many flow cytometry applications. This
function identifies a single such population, potentially from a mixture
of multiple populations.
\end{Description}
\begin{Usage}
\begin{verbatim}
lymphGate(x, channels, preselection=NULL, scale=2.5,
          bwFac=1.3, filterId="defaultLymphGate", evaluate=TRUE, ...)

lymphFilter(channels, preselection=as.character(NULL),
            scale=2.5, bwFac=1.3, filterId="defaultLymphFilter")

\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An object of class \code{\LinkA{flowSet}{flowSet}}. 
\item[\code{channels}] A character vector of length 2 of valid flow
parameters in \code{x}. 
\item[\code{preselection}] Either \code{NULL}, in which case this boils down
to fitting a regular \code{\LinkA{norm2Filter}{norm2Filter}}, a
character scalar giving one of the flow parameters in \code{x}, or a
named list of numerics specifying the initial rough
preselection. The latter gets passed on to
\code{\LinkA{rectangleGate}{rectangleGate}}, see it's documentation for
details. 
\item[\code{scale}] The \code{scaleFactor} parameter that gets passed on to
\code{norm2Filter}. 
\item[\code{bwFac}] The bandwidth factor that gets passed on to
\code{\LinkA{curv1Filter}{curv1Filter}}. 
\item[\code{filterId}] A character used as filterId. 
\item[\code{evaluate}] A logical indicating wether the filter should be
resolved (computation of the \code{\LinkA{filterResult}{filterResult}}
and the subset). 
\item[\code{...}] Additional arguments. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This algorithm does not apply real mixture modelling, however it is
able to identify a single elliptical cell population from a mixture of
multiple such populations. The idea is to first define a rough
rectangular preselection and, in a second step, fit a bivariate normal
distribution to this subset only.

Depending on the value of \code{preselection}, the initial rough
selection is either

\describe{

\item[NULL:] No preselection at all

\item[character scalar] Preselection based on cells that are
positive for a single marker only. This allows for back-gating,
for instances by selecting \code{CD4+} T-cells and using this
information to back-gate lymphocytes in \code{FSC} and
\code{SSC}. Positive cells are identified using a
\code{curv1Filter}. 

\item[a named list of numerics:] Preselection by a rectangular
gate. The items of the list have to be numerics of length one
giving the gate boundaries in the respective dimensions. 

The \code{lymphFilter} class and constructor provide the means to
treat \code{lymphGates} as regular \code{flowCore} filters.

}
\end{Details}
\begin{Value}
A list with items

\begin{ldescription}
\item[\code{x }] The filtered \code{flowSet}. 
\item[\code{n2gate }] The \code{norm2Filter} object. 
\item[\code{n2gateResults }] The \code{\LinkA{filterResult}{filterResult}} after
applying the \code{norm2Filter} on the \code{flowSet}. 
\end{ldescription}


for the \code{lymphGate} function. Note that \code{x} and
\code{n2gateResults} are \code{NULL} when \code{eval=FALSE}.

The \code{lymphFilter} constructor returns and object of class
\code{lymphFilter}, which can be used as a regular \code{flowCore}
fitler.
\end{Value}
\begin{Section}{Extends}
Class \code{"\LinkA{parameterFilter}{parameterFilter}"},
directly.

Class \code{"\LinkA{concreteFilter}{concreteFilter}"},
by class "parameterFilter", distance 2.

Class \code{"\LinkA{filter}{filter}"}, by class
"parameterFilter", distance 3.
\end{Section}
\begin{Section}{Slots}
See \code{Arguments} section for details.

\describe{

\item[\code{preselection}:] Object of class \code{character}, the
name of the flow parameter used for preselection. 

\item[\code{rectDef}:] Object of class \code{list}, the initial
rectangular selection. 

\item[\code{scale}:] Object of class \code{numeric}.

\item[\code{bwFac}:] Object of class \code{numeric}.

\item[\code{parameters}:] Object of class \code{parameters}, the flow
parameters to operate on. 

\item[\code{filterId}:] Object of class \code{"character"}, the
filter identifier. 

}
\end{Section}
\begin{Section}{Objects from the Class}
Objects can be created by calls of the form \code{new("lymphFilter",
    parameters, ...)} or using the constructor \code{lymphFilter}. The
constructor is the recommended way of object instantiation.
\end{Section}
\begin{Section}{Methods}
\describe{

\item[\%in\%] \code{signature(x =
        "flowFrame", table = "lymphFilter")}: the work horse for doing the
actual filtering. Internally, this simply calls the \code{lympghGate}
function. 

}
\end{Section}
\begin{Author}\relax
Florian Hahne
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{norm2Filter}{norm2Filter}}, \code{\LinkA{curv1Filter}{curv1Filter}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

data(GvHD)
dat <- GvHD[pData(GvHD)$Patient==10]
dat <- transform(dat, "FL4-H"=asinh(`FL4-H`))
lg <- lymphGate(dat, channels=c("FSC-H", "SSC-H"), preselection="FL4-H",scale=1.5)

if(require(flowViz))
xyplot(`SSC-H`~`FSC-H`, dat, filter=lg$n2gate)

## This is using the abstract lymphFilter class instead
lf <- lymphFilter(channels=c("FSC-H", "SSC-H"), preselection="FL4-H")
filter(dat, lf)

\end{ExampleCode}
\end{Examples}

