% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/detectSpatialContext.R
\name{detectSpatialContext}
\alias{detectSpatialContext}
\title{Detect the spatial context of each cell based on its neighborhood}
\usage{
detectSpatialContext(
  object,
  entry = "aggregatedNeighbors",
  threshold = 0.9,
  name = "spatial_context"
)
}
\arguments{
\item{object}{a \code{SingleCellExperiment} or \code{SpatialExperiment}
object}

\item{entry}{single character specifying the \code{colData(object)}
entry containing the \code{aggregateNeighbors} DataFrame output. 
Defaults to "aggregatedNeighbors".}

\item{threshold}{single numeric between 0 and 1 that specifies the fraction 
threshold for SC assignment. Defaults to 0.9.}

\item{name}{single character specifying the name of the output saved in 
\code{colData(object)}. Defaults to "spatial_context".}
}
\value{
returns an object of \code{class(object)} containing a new column 
entry to \code{colData(object)[[name]]}
}
\description{
Function to detect the spatial context (SC) of each cell. 
Based on its sorted (high-to-low) cellular neighborhood (CN) fractions in a 
spatial interaction graph, the SC of each cell is assigned as the set of CNs 
that cumulatively exceed a user-defined fraction threshold. 

The term was coined by \href{https://doi.org/10.1016/j.cels.2021.09.012}{
Bhate S. et al., Tissue schematics map the specialization of immune tissue 
motifs and their appropriation by tumors, Cell Systems, 2022} and describes 
tissue regions in which distinct CNs may be interacting.
}
\section{Spatial context background}{

The function relies on CN fractions for each cell in a 
spatial interaction graph (originally a k-nearest neighbor (KNN) graph).

We can retrieve the CN fractions using the \link[imcRtools]{buildSpatialGraph} 
and \link[imcRtools]{aggregateNeighbors} functions.

The window size (k for KNN) for \link[imcRtools]{buildSpatialGraph} should 
reflect a length scale on which biological signals can be exchanged and 
depends, among others, on cell density and tissue area. In view of their 
divergent functionality, we recommend to use a larger window size for SC 
(interaction between local processes) than for CN (local processes) detection.

Subsequently, the CN fractions are sorted from high-to-low and the SC of
each cell is assigned the minimal combination of SCs that additively
surpass a user-defined threshold. The default threshold of 0.9 aims to
represent the dominant CNs, hence the most prevalent signals, in a given window.

For more details, please refer to:
\href{https://doi.org/10.1016/j.cels.2021.09.012}{ Bhate S. et al., Tissue
schematics map the specialization of immune tissue motifs and their
appropriation by tumors, Cell Systems, 2022}.
}

\examples{
set.seed(22)
library(cytomapper)
data(pancreasSCE)

## 1. Cellular neighborhood (CN)
sce <- buildSpatialGraph(pancreasSCE, img_id = "ImageNb",
                        type = "knn",
                        name = "knn_cn_graph",
                        k = 5)

sce <- aggregateNeighbors(sce, colPairName = "knn_cn_graph",
                         aggregate_by = "metadata",
                         count_by = "CellType",
                         name = "aggregatedCellTypes")

cur_cluster <- kmeans(sce$aggregatedCellTypes, centers = 3)
sce$cellular_neighborhood <- factor(cur_cluster$cluster)

plotSpatial(sce, img_id = "ImageNb",
           colPairName = "knn_cn_graph",
           node_color_by = "cellular_neighborhood",
           scales = "free")

## 2. Spatial context (SC)
sce <- buildSpatialGraph(sce, img_id = "ImageNb",
                        type = "knn",
                        name = "knn_sc_graph",
                        k = 15)

sce <- aggregateNeighbors(sce, colPairName = "knn_sc_graph",
                         aggregate_by = "metadata",
                         count_by = "cellular_neighborhood",
                         name = "aggregatedNeighborhood")

# Detect spatial context
sce <- detectSpatialContext(sce, entry = "aggregatedNeighborhood",
                           threshold = 0.9)

plotSpatial(sce, img_id = "ImageNb",
           colPairName = "knn_sc_graph",
           node_color_by = "spatial_context",
           scales = "free")
           
}
\references{
\href{https://doi.org/10.1016/j.cels.2021.09.012}{
Bhate S. et al., Tissue schematics map the specialization of immune tissue 
motifs and their appropriation by tumors, Cell Systems, 2022}
}
\seealso{
\code{\link[imcRtools]{filterSpatialContext}} for the function to filter 
spatial contexts

\code{\link[imcRtools]{plotSpatialContext}} for the function to plot 
spatial context graphs
}
\author{
Lasse Meyer (\email{lasse.meyer@uzh.ch})
}
