Run PCA on a BANKSY matrix.

runBanksyPCA(
  se,
  use_agf = FALSE,
  lambda = 0.2,
  npcs = 20L,
  assay_name = NULL,
  scale = TRUE,
  group = NULL,
  M = NULL,
  seed = NULL,
  lazy = TRUE,
  pca_backend = c("cpp", "r"),
  coord_names = NULL,
  k_geom = 15L,
  spatial_mode = c("kNN_median", "kNN_r", "kNN_rn", "kNN_rank", "kNN_unif", "rNN_gauss"),
  split_scale = TRUE,
  num_cores = NULL,
  verbose = TRUE,
  ...
)

Arguments

se: A SpatialExperiment, SingleCellExperiment or SummarizedExperiment object with computeBanksy ran (not required when lazy=TRUE).
use_agf: A logical vector specifying whether to use the AGF for computing principal components. Ignored when lazy=TRUE.
lambda: A numeric vector in \(\in [0,1]\) specifying a spatial weighting parameter. Larger values (e.g. 0.8) incorporate more spatial neighborhood and find spatial domains, while smaller values (e.g. 0.2) perform spatial cell-typing.
npcs: An integer scalar specifying the number of principal components to compute.
assay_name: A string scalar specifying the name of the assay used in computeBanksy.
scale: A logical scalar specifying whether to scale features before PCA. Defaults to TRUE. Ignored when lazy=TRUE (always scales).
group: A string scalar specifying a grouping variable for samples in se. This is used to scale the samples in each group separately. When lazy=TRUE, also used for per-group kNN computation.
M: Advanced usage. An integer vector specifying the highest azimuthal Fourier harmonic to use. If specified, overwrites the use_agf argument. Ignored when lazy=TRUE.
seed: Seed for PCA. If not specified, no seed is set; when lazy=TRUE the solver then starts from a fixed vector and is reproducible. Supply a seed to vary that starting vector instead.
lazy: A logical scalar. If TRUE, compute PCA directly without materializing the full BANKSY matrix. Default FALSE.
pca_backend: A string scalar specifying the PCA backend when lazy=TRUE. "cpp" (default) uses C++ irlba for lower memory and faster runtime. "r" uses R's irlba package.
coord_names: A string vector specifying the names in colData corresponding to spatial coordinates. Only used when lazy=TRUE.
k_geom: An integer scalar specifying the number of neighbors to use. Only used when lazy=TRUE.
spatial_mode: A string scalar specifying the kernel for neighborhood computation. Only used when lazy=TRUE.
split_scale: A logical scalar specifying whether to scale features per group. Only used when lazy=TRUE and group is not NULL.
num_cores: An integer scalar specifying the number of cores for parallel kNN via mclapply. Only used when lazy=TRUE and group is not NULL.
verbose: A logical scalar specifying verbosity.
...: Additional arguments passed to computeNeighbors when lazy=TRUE.

Value

A SpatialExperiment / SingleCellExperiment / SummarizedExperiment object with PC coordinates in reducedDims(se).

Details

This function runs PCA on the BANKSY matrix (see getBanksyMatrix) with features scaled to zero mean and unit standard deviation.

When lazy=TRUE, PCA is computed without materializing the full BANKSY matrix in memory using an implicit linear operator. This enables analysis of very large datasets (millions of cells). The lazy path does not require computeBanksy to be run first — it computes the kNN graph internally. Currently only supported for M=0 (no AGF).

Examples

data(rings)
spe <- runBanksyPCA(rings, assay_name = "counts", lambda = 0.2, npcs = 20)
#> Computing neighbors...
#> Spatial mode is kNN_median
#> Parameters: k_geom=15
#> Done
#> Building sparse weight matrix
#> Computing scaling parameters for own expression
#> Computing clipping excess for own expression
#> Computing scaling params and clipping for H0
#> H0 genes requiring clipping: 0 / 50
#> Clipping corrections: own=0 H0=0 entries
#> Computing BANKSY PCA (20 PCs) via C++ irlba (work=27)
#>   iter=1  mprod=54  sv[20]=8.5000e+00  t=0s
#>   iter=2  mprod=68  sv[20]=1.1893e+01  t=0s
#>   iter=5  mprod=110  sv[20]=1.4406e+01  t=0s
#>   iter=8  mprod=152  sv[20]=1.4489e+01  t=0s
#>   Converged: iter=8, mprod=152
#> Done.