% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nestedClusters.R
\name{nestedClusters}
\alias{nestedClusters}
\title{Map nested clusterings}
\usage{
nestedClusters(ref, alt)
}
\arguments{
\item{ref}{A character vector or factor containing one set of groupings, considered to be the reference.}

\item{alt}{A character vector or factor containing another set of groupings, to be compared to \code{alt}.}
}
\value{
A list containing:
\itemize{
\item \code{proportions}, a matrix where each row corresponds to one of the \code{alt} clusters and each column corresponds to one of the \code{ref} clusters.
Each matrix entry represents the proportion of cells in \code{alt} that are assigned to each cluster in \code{ref}.
(That is, the proportions across all \code{ref} clusters should sum to unity for each \code{alt} cluster.)
\item \code{alt.mapping}, a \linkS4class{DataFrame} with one row per cluster in \code{alt}.
This contains the columns \code{max}, a numeric vector specifying the maximum value of \code{statistic} for that \code{alt} cluster;
and \code{which}, a character vector specifying the \code{ref} cluster in which the maximum value occurs.
\item \code{ref.score}, a numeric vector of length equal to the number of \code{ref} clusters.
This represents the degree of nesting of \code{alt} clusters within each \code{ref} cluster, see Details.
}
}
\description{
Map an alternative clustering to a reference clustering,
where the latter is expected to be nested within the former.
}
\details{
This function identifies mappings between two clusterings on the same set of cells where \code{alt} is potentially nested within \code{ref} (e.g., as it is computed at higher resolution).
To do so, we take each \code{alt} cluster and compute the the proportion of its cells that are derived from each \code{ref} cluster.
The corresponding \code{ref} cluster is identified as that with the highest proportion, as reported by the \code{which} field in the \code{mapping} DataFrame. 

The quality of the mapping is determined by \code{max} in the output \code{mapping} DataFrame.
A low value indicates that \code{alt} does not have a clear counterpart in \code{ref}, representing loss of heterogeneity.
Note that this is not a symmetrical inference; multiple \code{alt} clusters can map to the same \code{ref} cluster without manifesting as a low \code{max}.
This implicitly assumes that an increase in resolution in \code{alt} is not problematic.

The \code{ref.score} value for each cluster \code{ref} is formally defined as the probability of randomly picking a cell that belongs to \code{ref},
conditional on the event that the chosen cell belongs to the same \code{alt} cluster as a randomly chosen cell from \code{ref}.
This probability is equal to unity when \code{ref} is an exact superset of all \code{alt} clusters that contain its cells, corresponding to perfect 1:many nesting.
In contrast, if the \code{alt} clusters contain a mix of cells from different \code{ref}, this probability will be low and can be used as a diagnostic for imperfect nesting.
}
\examples{
m <- matrix(runif(10000), ncol=10)
clust1 <- kmeans(m,10)$cluster
clust2 <- kmeans(m,20)$cluster
nestedClusters(clust1, clust2)

# The ref.score is 1 in cases of perfect nesting.
nestedClusters(clust1, clust1)$ref.score

nest.clust <- paste0(clust1, sample(letters, length(clust1), replace=TRUE))
nestedClusters(clust1, nest.clust)$ref.score

# In contrast, it is much lower when nesting is bad.
nestedClusters(clust1, sample(clust1))$ref.score

}
\seealso{
\code{\link{linkClusters}}, to do this in a symmetric manner (i.e., without nesting).

\code{\link{pairwiseRand}}, for another way of comparing two sets of clusterings.
}
