Package 'smoothclust'

Title: smoothclust
Description: Method for identification of spatial domains and spatially-aware clustering in spatial transcriptomics data. The method generates spatial domains with smooth boundaries by smoothing gene expression profiles across neighboring spatial locations, followed by unsupervised clustering. Spatial domains consisting of consistent mixtures of cell types may then be further investigated by applying cell type compositional analyses or differential analyses.
Authors: Lukas M. Weber [aut, cre] (ORCID: <https://orcid.org/0000-0002-3282-1730>)
Maintainer: Lukas M. Weber <[email protected]>
License: MIT + file LICENSE
Version: 1.9.3
Built: 2026-07-14 21:43:58 UTC
Source: https://github.com/bioc/smoothclust

Help Index

Boundary density metric

Description

Function for boundary density metric

Usage

boundary_density(
  spatial_coords,
  labels,
  k = 6,
  n_threads = 1,
  adjust = c("none", "analytic", "permutation"),
  n_permutations = 1000,
  seed = NULL
)

Arguments

spatial_coords

Numeric matrix containing spatial coordinates of points, formatted as nrow = number of points, ncol = 2 (assuming x and y dimensions). For example, 'spatial_coords = spatialCoords(spe)' if using a SpatialExperiment object.
labels

Atomic vector or factor containing cluster labels for each point. Missing values are not allowed. For example, 'labels <- colData(spe)$label' if using a SpatialExperiment object.
k

Number of k nearest neighbors to use in calculation. Default = 6 (e.g. for hexagonal arrangement in 10x Genomics Visium platform).
n_threads

Number of threads to use for nearest-neighbor searches. Default = 1.
adjust

Composition adjustment to calculate. Options are "none", "analytic", and "permutation". With "none", only the raw boundary density is returned. With "analytic", the raw boundary density is compared to a deterministic expectation based on the observed label counts. With "permutation", labels are randomly permuted across spatial locations n_permutations times. Default = "none".
n_permutations

Number of random label permutations to use when adjust = "permutation". Default = 1000.
seed

Optional random seed to use when adjust = "permutation". Default = NULL.

Details

Function to calculate the raw boundary density metric, defined as the average fraction of nearest neighbors per point that are from a different cluster. This metric can be used to quantify and compare the relative density of the boundaries of clusters or spatial domains. Optional composition adjustments can be used to compare the raw boundary density to an expected value under random relabeling.

Value

Returns a list containing values at each point (i.e. the number of nearest neighbors that are from a different cluster, the number of nearest neighbors, and the local raw boundary density) as well as the mean discordant neighbor count and the sample-level raw boundary density. If adjust = "analytic", the list also contains the expected boundary density, relative boundary density, and excess boundary density. If adjust = "permutation", the list also contains the permutation mean, standard deviation, relative boundary density, standardized score, and number of permutations.

Examples

spatial_coords <- cbind(c(0, 1, 3, 6), 0)
labels <- c("A", "B", "A", "A")

# calculate raw boundary density metric
res <- boundary_density(spatial_coords, labels, k = 2)
str(res)
res$n_discordant
res$mean_discordant
res$boundary_density

# calculate analytic composition adjustment
res_adj <- boundary_density(spatial_coords, labels, k = 2, 
                            adjust = "analytic")
res_adj$expected_boundary_density
res_adj$relative_boundary_density

smoothclust

Description

Method for identification of spatial domains and spatially-aware clustering.

Usage

smoothclust(
  input,
  assay_name = "counts",
  spatial_coords = NULL,
  method = c("uniform", "kernel", "knn"),
  bandwidth = 0.05,
  k = 18,
  truncate = 0.05,
  n_threads = 1
)

Arguments

input

Input data, which can be provided as either a SpatialExperiment object or a numeric matrix. If this is a SpatialExperiment object, it is assumed to contain either raw expression counts or logcounts in the assay slots and spatial coordinates in the spatialCoords slot. If this is a numeric matrix, it is assumed to contain either raw expression counts or logcounts, and spatial coordinates need to be provided separately with the spatial_coords argument.
assay_name

For a SpatialExperiment input object, this argument specifies the name of the assay containing the expression values to be smoothed. In most cases, this will be counts, which contains raw expression counts. Alternatively, logcounts may also be used. Note that if logcounts are used, the smoothed values represent geometric averages. This argument is only used if the input is a SpatialExperiment object. Default = counts.
spatial_coords

Numeric matrix of spatial coordinates, assumed to contain x coordinates in first column and y coordinates in second column. This argument is only used if the input is a numeric matrix.
method

Method used for smoothing. Options are uniform, kernel, and knn. The uniform method calculates unweighted averages across spatial locations within a circular window with radius bandwidth at each spatial location, which smooths out spatial variability as well as sparsity due to sampling variability. The kernel method calculates a weighted average using a truncated exponential kernel applied to Euclidean distances with a length scale parameter equal to bandwidth, which provides a more sophisticated approach to smoothing out spatial variability but may be affected by sparsity due to sampling variability (especially sparsity at the index point), and is computationally slower. The knn method calculates an unweighted average across the index point and its k nearest neighbors, and is the fastest method. Default = uniform.
bandwidth

Bandwidth parameter for smoothing, expressed as proportion of width or height (whichever is greater) of tissue area. Only used for method = "uniform" or method = "kernel". For method = "uniform", the bandwidth represents the radius of a circle, and unweighted averages are calculated across neighboring points within this circle. For method = "kernel", the averaging is weighted by distances scaled using a truncated exponential kernel applied to Euclidean distances. For example, a bandwidth of 0.05 will smooth values across neighbors weighted by distances scaled using a truncated exponential kernel with length scale equal to 5 area. Weights for method = "kernel" are truncated at small values for computational efficiency. Default = 0.05.
k

Number of nearest neighbors parameter for method = "knn". Only used for method == "knn". Unweighted averages are calculated across the index point and its k nearest neighbors. Default = 18 (based on two layers in honeycomb pattern for 10x Genomics Visium platform).
truncate

Truncation threshold parameter if method = "kernel". Kernel weights below this value are set to zero for computational efficiency. Only used for method = "kernel". Default = 0.05.
n_threads

Number of threads to use for nearest-neighbor searches. Default = 1.

Details

Method for identification of spatial domains and spatially-aware clustering in spatial transcriptomics data.

Method for identification of spatial domains and spatially-aware clustering in spatial transcriptomics data. The method generates spatial domains with smooth boundaries by smoothing gene expression profiles across neighboring spatial locations, followed by unsupervised clustering. Spatial domains consisting of consistent mixtures of cell types may then be further investigated by applying cell type compositional analyses or differential analyses.

Value

Returns spatially smoothed expression values, which can then be used as the input for further downstream analyses. Results are returned either as a SpatialExperiment object containing a new assay named <assay_name>_smooth (e.g. counts_smooth or logcounts_smooth), or as a numeric matrix, depending on the input type.

Examples

set.seed(123)
input <- matrix(rpois(60, lambda = 10), nrow = 10)
spatial_coords <- cbind(rep(1:3, each = 2), rep(1:2, times = 3))

# smooth a numeric expression matrix
out <- smoothclust(input, spatial_coords = spatial_coords, bandwidth = 0.6)
dim(out)