% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/AllGenerics.R, R/cluster.R
\docType{methods}
\name{cluster}
\alias{cluster}
\alias{cluster,daFrame-method}
\title{FlowSOM clustering & ConsensusClusterPlus metaclustering}
\usage{
cluster(x, ...)

\S4method{cluster}{daFrame}(x, cols_to_use, xdim = 10, ydim = 10,
  maxK = 20, seed = 1)
}
\arguments{
\item{x}{a \code{\link{daFrame}}.}

\item{...}{optional arguments.}

\item{cols_to_use}{a character vector. Specifies which antigens to use for clustering.}

\item{xdim, ydim}{numeric. Specify the grid size of the self-orginizing map. 
The default 10x10 grid will yield 100 clusters.}

\item{maxK}{numeric. Specifies the maximum number of clusters to evaluate
in the metaclustering. For \code{maxK = 20}, for example, 
metaclustering will be performed for 2 through 20 clusters.}

\item{seed}{numeric. Sets random seed in \code{ConsensusClusterPlus()}.}
}
\value{
The function will add information to the following slots 
of the input \code{daFrame} (and return it):
\itemize{
\item{\code{rowData}\itemize{
\item{\code{cluster_id}:
  each cell's cluster ID as inferred by \code{FlowSOM}. 
  One of 1, ..., \code{xdim}x\code{ydim}.}
}}
\item{\code{colData}\itemize{
\item{\code{marker_class}: 
  \code{"type"} or \code{"state"}. 
  Specifies whether an antigen has been used for clustering 
  or not, respectively.}
}}
\item{\code{metadata}\itemize{
\item{\code{SOM_codes}:
  a table with dimensions K x (# cell type markers), 
  where K = \code{xdim} x \code{ydim}. Contains the SOM codes.}
\item{\code{cluster_codes}:
  a table with dimensions K x (\code{maxK} + 1). 
  Contains the cluster codes for all metaclustering.}
\item{\code{delta_area}: 
  a \code{\link{ggplot}} object. See above for details.}
}}
}
}
\description{
\code{cluster} will first group cells into \code{xdim}x\code{ydim} 
clusters using \pkg{FlowSOM}, and subsequently perform metaclustering 
with \pkg{ConsensusClusterPlus} into 2 through \code{maxK} clusters. 
In the returned \code{daFrame}, those antigens used for clustering will be 
labelled as '\code{type}' markers, and the remainder of antigens as 
'\code{state}' markers.
}
\details{
The delta area represents the amount of extra cluster stability gained when 
clustering into k groups as compared to k-1 groups. It can be expected that 
high stability of clusters can be reached when clustering into the number of 
groups that best fits the data. The "natural" number of clusters present in 
the data should thus corresponds to the value of k where there is no longer 
a considerable increase in stability (pleateau onset).
}
\examples{
data(PBMC_fs, PBMC_panel, PBMC_md)
re <- daFrame(PBMC_fs, PBMC_panel, PBMC_md)

# specify antigens to use for clustering
lineage <- c("CD3", "CD45", "CD4", "CD20", "CD33", 
    "CD123", "CD14", "IgM", "HLA_DR", "CD7")
(re <- cluster(re, cols_to_use=lineage))

}
\references{
Nowicka M, Krieg C, Weber LM et al. 
CyTOF workflow: Differential discovery in 
high-throughput high-dimensional cytometry datasets.
\emph{F1000Research} 2017, 6:748 (doi: 10.12688/f1000research.11622.1)
}
\author{
Helena Lucia Crowell \email{crowellh@student.ethz.ch}
}
