runBayesSpaceClustering: Clustering with BayesSpace

In theMILOlab/SPATA2: A Toolbox for Spatial Expression Analysis

Clustering with BayesSpace

Description

A wrapper around the BayesSpace clustering pipeline introduced by Zhao et al. (2021).

Usage

runBayesSpaceClustering(
  object,
  name = "bayes_space",
  n.Pcs = 15,
  n.HVGs = 2000,
  skip.PCA = FALSE,
  log.normalize = TRUE,
  assay.type = "logcounts",
  BSPARAM = BiocSingular::ExactParam(),
  qs = 3:15,
  burn.in = c(100, 1000),
  nrep = c(1000, 50000),
  use.dimred = "PCA",
  d = 15,
  init.method = "mclust",
  model = "t",
  gamma = 3,
  mu0 = NULL,
  lambda0 = NULL,
  alpha = 1,
  beta = 0.01,
  save.chain = FALSE,
  chain.fname = NULL,
  prefix = "B",
  return_model = TRUE,
  empty_remove = FALSE,
  overwrite = FALSE,
  assign_sce = FALSE,
  assign_envir = .GlobalEnv,
  seed = 123,
  verbose = NULL,
  ...
)

Arguments

object	An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.
name	Character value. The name the cluster variable has in the feature data of the SPATA2 object. Defaults to bayes_space.
n.HVGs	Number of highly variable genes to run PCA upon.
skip.PCA	Skip PCA (if dimensionality reduction was previously computed.)
log.normalize	Whether to log-normalize the input data with scater. May be omitted if log-normalization previously computed.
assay.type	Name of assay in sce containing normalized counts. Leave as "logcounts" unless you explicitly pre-computed a different normalization and added it to sce under another assay. Note that we do not recommend running BayesSpace on PCs computed from raw counts.
BSPARAM	A BiocSingularParam object specifying which algorithm should be used to perform the PCA. By default, an exact PCA is performed, as current spatial datasets are generally small (<10,000 spots). To perform a faster approximate PCA, please specify FastAutoParam() and set a random seed to ensure reproducibility.
qs	The values of q to evaluate. If qs is only one value exactly that is given to q of BayesSpace::spatialCluster(). Else the optimal q from all provided values is identified using BayesSpace::qTune().
burn.in, nrep	Integers specifying the range of repetitions to compute.
use.dimred	Name of a reduced dimensionality result in reducedDims(sce). If provided, cluster on these features directly.
d	Number of top principal components to use when clustering.
init.method	If init is not provided, cluster the top d PCs with this method to obtain initial cluster assignments.
model	Error model. ('normal' or 't')
gamma	Smoothing parameter. Defaults to 2 for platform="ST" and 3 for platform="Visium". (Values in range of 1-3 seem to work well.)
mu0	Prior mean hyperparameter for mu. If not provided, mu0 is set to the mean of PCs over all spots.
lambda0	Prior precision hyperparam for mu. If not provided, lambda0 is set to a diagonal matrix 0.01 I.
alpha	Hyperparameter for Wishart distributed precision lambda.
beta	Hyperparameter for Wishart distributed precision lambda.
save.chain	If true, save the MCMC chain to an HDF5 file.
chain.fname	File path for saved chain. Tempfile used if not provided.
prefix	Character value. Prefix of the cluster groups.
overwrite	Logical value. If TRUE, name overwrites features in feature data of the SPATA2 object.
assign_sce	Character value or NULL. If character, specifies the name under which the bayes space output (object of class SingleCellExperiment) is assigned to the global environment. This makes the whole output of the bayes space pipeline available instead of only adding the clustering output as a grouping variable to the SPATA2 object.
verbose	Logical. If TRUE, informative messages regarding the computational progress will be printed. (Warning messages will always be printed.)
...	Additional arguments given to BayesSpace::spatialCluster(). Exception: sce, q are specified within the function.
q_force	Numeric value or FALSE. If numeric, it forces the number of output clusters with input value. If FALSE, the optimal number of clusters is chosen for q determined by the elbow point of BayesSpace::qTune().

Details

This function is a wrapper around readVisium(), spatialPreprocess(), qTune() and spatialCluster() of the BayesSpace package. The results are stored in form of a grouping variable in the feature data.frame of the returned SPATA2 object.

Value

The updated input object, containing the added, removed or computed results.

References

Zhao E, Stone MR, Ren X, Guenthoer J, Smythe KS, Pulliam T, Williams SR, Uytingco CR, Taylor SEB, Nghiem P, Bielas JH, Gottardo R. Spatial transcriptomics at subspot resolution with BayesSpace. Nat Biotechnol. 2021 Nov;39(11):1375-1384. doi: 10.1038/s41587-021-00935-2. Epub 2021 Jun 3. PMID: 34083791; PMCID: PMC8763026.

See Also

plotLoglik(), find_elbow_point()

Examples

library(SPATA2)

data("example_data")

object <- example_data$object_UKF313T_diet

# tests options for q from 3 to 15 and picks the best
object <- runBayesSpaceClustering(object, name = "new_bspace", qs = 3:15)

plotLoglik(object)

# run with q = 10 to force 10 clusters in the output
object <- runBayesSpaceClustering(object, name = "bspace_10", qs = 10)

theMILOlab/SPATA2 documentation built on Feb. 8, 2025, 11:41 p.m.