Skip to contents

SigDoTS: statistical significance testing for domain detection in spatial transcriptomics

Domain-detection methods divide a tissue into as many domains as they are asked for. SigDoTS tests which of these domains the data support:

  • It starts from more candidate domains than you expect.
  • It arranges them in a tree and tests each split against a single-domain model.
  • It keeps a split only if it is significant, with error control over the whole tree.

The three steps of SigDoTS: initial candidate domains, a spatially constrained hierarchy, and tests from the root downward

The three steps of SigDoTS (Figure 1c of the paper).

Key features

  • Tests, not thresholds. Every retained split has passed a test against a single-domain null model that includes within-domain spatial correlation and gene-gene covariance; the family-wise error rate over all tests is controlled at alpha (0.05 by default).
  • Accounts for selection. The same clustering procedure that produced the candidate domains is applied to every simulated dataset, so the “separation that clustering always finds” is part of the reference distribution.
  • Works with your objects. Takes a Seurat object, a SpatialExperiment object, or plain matrices; writes the domains back with add_domains().
  • Works with your pipeline. Start from the built-in k-means, from BANKSY or BayesSpace, or from any labels you already have (candidate_labels).
  • Readable results. print() draws the tested tree in the console; summary() lists every test with its statistic, p-value and level; plot() draws the domains, the candidate domains, the tree and the estimated spatial correlation.
  • Reproducible and parallel. Same data, arguments and seed give the same result on any number of cores.
  • Scales. A Vecchia approximation (default) keeps memory roughly linear in the number of spots; the exact computation is available for smaller samples.

Installation

SigDoTS needs R 4.3.0 or later. It depends on the CRAN packages GpGp, fields, igraph, Matrix, RANN and ggplot2, which are installed automatically when SigDoTS is installed from GitHub.

# install.packages("remotes")
remotes::install_github("Yan-Lab-MSU/SigDoTS")

Or from a downloaded package file (the dependencies are then not installed automatically):

install.packages(c("GpGp", "fields", "igraph", "RANN", "ggplot2"))
install.packages("path/to/SigDoTS_0.2.5.10.tar.gz", repos = NULL, type = "source")

On a new computer, installing the dependencies takes a few minutes; SigDoTS itself installs in seconds and contains no compiled code. GpGp does, but on Windows and macOS CRAN provides a ready-made binary of it, so no compiler is needed.

On Linux, igraph needs the GLPK library of the operating system. If library(SigDoTS) stops with “libglpk.so.40: cannot open shared object file”, install the system libraries igraph uses and then igraph again, for example on Ubuntu or Debian:

sudo apt-get install libglpk-dev libgmp-dev libxml2-dev

(on Fedora: sudo dnf install glpk-devel gmp-devel libxml2-devel).

Tested on Windows, macOS and Linux: R CMD check --as-cran passes on Windows (R 4.6.2), macOS (R 4.6.2, Apple silicon) and Ubuntu (R 4.5.3, R 4.6.2 and the development version of R) on GitHub Actions, and in clean Ubuntu 24.04 containers with R 4.6.1; the package also runs with R 4.3.2, R 4.4.2 and R 4.5.1 on Linux.

Optional, only to make the candidate domains with BANKSY or BayesSpace:

install.packages("BiocManager")
BiocManager::install(c("Banksy", "SingleCellExperiment", "SummarizedExperiment"))   # or "BayesSpace"

Quick start

The package includes a small simulated dataset: 900 spots on a 30 x 30 grid, 200 genes, three true domains of 300 spots each.

library(SigDoTS)
dim(sigdots_example$x)          # spots x genes
#> [1] 900 200
fit <- sigdots(sigdots_example$x, sigdots_example$coords, K0 = 5)
#> SigDoTS: 900 spots, 200 genes; 5 candidate domains; testing from the top of the tree
#>   test at node 9 (900 spots, 5 candidate domains): split (19 simulated datasets) [10 s]
#>   test at node 7 (300 spots, 2 candidate domains): no split (10 simulated datasets) [2 s]
#>   test at node 8 (600 spots, 3 candidate domains): split (30 simulated datasets) [7 s]
#>   test at node 6 (300 spots, 2 candidate domains): no split (15 simulated datasets) [2 s]
fit
#> SigDoTS: 900 spots, 200 genes
#> Number of domains: 3   (spots per domain: 300, 300, 300)
#> 
#> Split tree ([node] spots, candidate domains: decision):
#> [9] 900 spots, candidate domains 1,2,3,4,5: split
#> ├── [7] 300 spots, candidate domains 2,3: no split   => DOMAIN 1
#> │   ├── candidate domain 2  109 spots
#> │   └── candidate domain 3  191 spots
#> └── [8] 600 spots, candidate domains 1,4,5: split
#>     ├── [4] 300 spots, candidate domain 4   => DOMAIN 2
#>     └── [6] 300 spots, candidate domains 1,5: no split   => DOMAIN 3
#>         ├── candidate domain 1  103 spots
#>         └── candidate domain 5  197 spots
#> 
#> Use summary() for the tests.

The three domains match the three true regions:

table(domain = domains(fit)$domain, true_region = sigdots_example$region)
#>       true_region
#> domain   1   2   3
#>      1   0   0 300
#>      2   0 300   0
#>      3 300   0   0
plot(fit)

plot(fit, type = "tree")

summary(fit) adds a table of the tests (statistic, number of simulated datasets, p-value, level, decision). The Getting started tutorial explains every line of this output.

Input data format

sigdots() takes the data in the form you have it:

You have Call
a Seurat object (normalised, with variable genes set) sigdots(obj, K0 = 10)
a SpatialExperiment object (with a logcounts assay) sigdots(spe, K0 = 10, genes = hvg)
a raw counts matrix (genes x spots) and a coordinate table sigdots(sigdots_prepare(counts), xy, K0 = 10)
a normalised expression matrix (spots x genes) and coordinates sigdots(x, xy, K0 = 10)

plus one number, K0, the number of candidate domains (more than the number of domains you expect). Instead of K0 you can give your own over-segmentation with candidate_labels, a vector or the name of a metadata column. add_domains(obj, fit) writes the domains back into a Seurat or SpatialExperiment object. See Using SigDoTS on your own data.

Tutorials

  • Getting started: the demo above, line by line.
  • Real data application: a public Visium section of human brain cortex with manually labelled layers, from download to the domains, and one layer analysed on its own.
  • Using SigDoTS on your own data: the five input forms (Seurat, SpatialExperiment, Scanpy file, counts, matrices), the choice of the candidate domains, exact or approximate spatial computation, run time and memory.
  • Troubleshooting and FAQ: every error and warning the package can give, and what to do.
  • How SigDoTS works: the method step by step, without formulas.

All but the real-data application are also installed with the package: vignette("SigDoTS"), vignette("own-data"), vignette("faq"), vignette("how-it-works").

How long does it take?

Measured in the paper’s scalability experiment (simulated data with 2,000 genes and three domains, K0 = 5, exact spatial computation, 10 cores; mean of 2 datasets per size; peak memory of the whole run including the 10 worker processes):

Spots Run time Peak memory
400 14 s 2.7 GiB
900 32 s 3.5 GiB
1,600 2.0 min 5.3 GiB
2,500 4.3 min 6.1 GiB
5,041 9.2 min 9.6 GiB
10,000 18 min 19.8 GiB

With the default Vecchia approximation, 2,500 spots took a median of 4.0 minutes on three-domain data and 1.4 minutes on one-domain data (10 cores, 680 datasets). Beyond about 20,000 spots use the Vecchia approximation: the exact computation at 50,176 spots took 12 hours and 206 GiB.

How SigDoTS works, in brief

  1. Candidate domains. k-means on the first 15 principal components (or BayesSpace, BANKSY, or your own labels) divides the spots into K0 candidate domains.
  2. Tree. Groups that touch in space are merged pairwise, the most similar first (Ward’s criterion on the candidate domains’ means in the first 15 principal components), into a binary tree.
  3. Tests from the top. At each split, the statistic is the within-group sum of squares divided by the total sum of squares, over all genes (smaller means a clearer split). A single-domain model is fitted to the spots of that part of the tree: a matrix-normal model whose spatial correlation (strength eta, range ell, Matérn 3/2) is estimated from pairs of spots within the same candidate domain, and whose gene covariance is estimated after removing each candidate domain’s mean. Datasets simulated from it are clustered in the same way, and the p-value is (1 + the number of them that split at least as clearly as the data) / (1 + the number of simulated datasets); a normal approximation that needs fewer simulated datasets is available (pvalue_method = "normal_adaptive"). A test on m of the n spots uses the level alpha * (m - 1) / (n - 1).
  4. Domains. A part is split only when its test is significant; otherwise it is a domain.

Citation

Manuscript in preparation. Until it is published, please cite the package: citation("SigDoTS").

Licence and contact

SigDoTS is released under the MIT licence (LICENSE.md). Questions and bug reports: open an issue on GitHub, or write to the maintainer (maintainer("SigDoTS")).