Find spatial niches by clustering PhiSpace scores

Identifies spatial niches by performing k-means clustering on PhiSpace cell type scores. Optionally performs PCA before clustering to reduce dimensionality and improve clustering performance. Can test multiple numbers of niches and return all results for comparison.

findNiches(
  spe,
  reducedDimName = "PhiSpace",
  n_niches,
  use_pca = TRUE,
  ncomp = NULL,
  center = TRUE,
  scale = FALSE,
  kmeans_iter = 500L,
  kmeans_nstart = 20L,
  kmeans_algorithm = "Lloyd",
  seed = 94863,
  store_pca = FALSE,
  pca_name = "PhiSpace_PCA",
  verbose = TRUE
)

Arguments

spe

SpatialExperiment or SingleCellExperiment object containing PhiSpace scores.

reducedDimName

Name of the reducedDim containing PhiSpace scores (default: "PhiSpace").

n_niches

Integer or vector of integers. Number(s) of niches (clusters) to identify. If a vector is provided, multiple clustering results will be generated.

use_pca

Logical. Whether to perform PCA before clustering (default: TRUE).

ncomp

Integer. Number of principal components to use if use_pca = TRUE. If NULL, defaults to half the number of cell types in PhiSpace scores.

center

Logical. Whether to center data for PCA (default: TRUE).

scale

Logical. Whether to scale data for PCA (default: FALSE).

kmeans_iter

Integer. Maximum number of iterations for k-means (default: 500).

kmeans_nstart

Integer. Number of random starts for k-means (default: 20).

kmeans_algorithm

Character. Algorithm for k-means clustering (default: "Lloyd").

seed

Integer. Random seed for reproducibility (default: 94863). The function sets the seed with withr::local_seed(), so the session's random-number state is restored on exit.

store_pca

Logical. Whether to store PCA results in the object (default: FALSE).

pca_name

Character. Name for stored PCA results if store_pca = TRUE (default: "PhiSpace_PCA").

verbose

Logical. Whether to report progress and niche sizes with message() (default: TRUE). Use verbose = FALSE or suppressMessages() to silence them.

Value

The input object with niche assignments added to colData. If a single n_niches is provided, results are stored as "spatial_niches". If multiple n_niches are provided, results are stored as "spatial_niches_k7", "spatial_niches_k8", etc. If store_pca = TRUE, PCA results are also stored in reducedDims.

Details

This function identifies spatial niches by clustering cells/spots based on their PhiSpace cell type composition scores. The workflow consists of:

1. Extract PhiSpace scores from the specified reducedDim

2. Optionally perform PCA to reduce dimensionality and focus on major patterns

3. Apply k-means clustering to identify niches (for each k in n_niches)

4. Store niche assignments in colData

PCA is recommended when you have many cell types (>20) as it can improve clustering by focusing on the main axes of variation in cell type composition.

When multiple values of n_niches are provided, the function will test each one and store all results, allowing you to compare different numbers of niches and choose the most appropriate one for your analysis.

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
spe <- SpatialExperiment::SpatialExperiment(
  assays = list(logcounts = logcounts(query)),
  spatialCoords = cbind(x = runif(100), y = runif(100))
)
spe <- PhiSpace(ref, spe, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                ncomp = 3)
spe <- findNiches(spe, n_niches = 3, ncomp = 3, verbose = FALSE)
table(spe$spatial_niches)