This page covers what to prepare and which options to consider when you run SigDoTS on a real dataset. Section 1 runs on small objects built from the example data; the rest is shown without running, because it needs your data. A complete run on a public Visium section (human dorsolateral prefrontal cortex, 151673) is the real data application.
1. Input data: what sigdots() accepts
sigdots() takes the data in whichever of these forms you
have:
| You have | Call | Where the pieces come from |
|---|---|---|
a Seurat object (Visium, Xenium, Slide-seq, …
loaded with Load10X_Spatial() or similar) |
sigdots(obj, K0 = 10) |
the normalised "data" layer of the default assay; the
variable genes from FindVariableFeatures(); the positions
from the object’s image or FOV |
a SpatialExperiment object (Bioconductor:
read10xVisium(), spatialLIBD, STexampleData, …) |
sigdots(spe, K0 = 10, genes = hvg) |
the "logcounts" assay; the genes you name (all genes if
there are at most 5,000); spatialCoords(spe)
|
a SingleCellExperiment without positions, or an
AnnData file read with zellkonverter::readH5AD()
|
sigdots(sce, coords = xy, K0 = 10) |
the "logcounts" assay; coords given by
you |
| a counts matrix (genes x spots) and a coordinate table | sigdots(sigdots_prepare(counts), xy, K0 = 10) |
sigdots_prepare() log-normalises and keeps the 2,000
most variable genes |
| an expression matrix you normalised yourself | sigdots(x, xy, K0 = 10) |
x: one row per spot, one column per gene;
xy: one row per spot, two columns, same order |
Whatever the form, two things end up inside: an expression matrix
with one row per spot and one column per gene, normalised and
log-transformed, and the spots’ positions (any unit; SigDoTS measures
distances in units of the typical distance between neighbouring spots).
candidate_labels can be the name of a metadata column of
the object (for example a BANKSY or Seurat clustering) instead of a
vector.
The examples below build small objects from the package’s example data, so that they run here; with real data the objects come from the loading functions named in the table.
All three examples start from the same toy counts matrix, made from the example data:
library(SigDoTS)
counts <- Matrix::Matrix(t(round(expm1(sigdots_example$x) * 50)), sparse = TRUE) # genes x spots
dim(counts)
#> [1] 200 900A Seurat object
library(Seurat)
# A toy Seurat object: the counts and the spot positions as a FOV. With real data:
# obj <- Load10X_Spatial("path/to/spaceranger/outs")
obj <- CreateSeuratObject(counts = counts, assay = "Spatial")
obj[["slice1"]] <- CreateFOV(CreateCentroids(data.frame(sigdots_example$coords, cell = colnames(counts))),
type = "centroids", assay = "Spatial")
obj <- NormalizeData(obj, verbose = FALSE) # the "data" layer SigDoTS uses
obj <- FindVariableFeatures(obj, nfeatures = 150, verbose = FALSE) # the genes SigDoTS uses
fit <- sigdots(obj, K0 = 5, verbose = FALSE)
fit
#> SigDoTS: 900 spots, 150 genes
#> Number of domains: 3 (spots per domain: 300, 295, 305)
#>
#> Split tree ([node] spots, candidate domains: decision):
#> [9] 900 spots, candidate domains 1,2,3,4,5: split
#> ├── [6] 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
#> ├── [1] 295 spots, candidate domain 1 => DOMAIN 2
#> └── [7] 305 spots, candidate domains 4,5: no split => DOMAIN 3
#> ├── candidate domain 4 154 spots
#> └── candidate domain 5 151 spots
#>
#> Use summary() for the tests.
obj <- add_domains(obj, fit) # adds obj$sigdots_domain and obj$sigdots_candidate_domain
table(obj$sigdots_domain, sigdots_example$region)
#>
#> 1 2 3
#> 1 0 0 300
#> 2 295 0 0
#> 3 5 300 0With a Seurat object you can also name the assay
(assay = "SCT"), choose the genes
(genes = VariableFeatures(obj)[1:1000]), give the positions
yourself (coords = ...), or start from a clustering stored
in the metadata (candidate_labels = "seurat_clusters").
Seurat objects created with Seurat 4 (images of class
VisiumV1) work the same way; their coordinates are
imagecol and imagerow, so
plot(fit) may appear flipped vertically relative to the
tissue image (add ggplot2::scale_y_reverse()).
A SpatialExperiment object
library(SpatialExperiment)
library(scuttle)
library(scran)
# A toy SpatialExperiment: with real data, spe <- read10xVisium("path/to/spaceranger/outs")
spe <- SpatialExperiment(assays = list(counts = counts), spatialCoords = sigdots_example$coords)
spe <- logNormCounts(spe) # the "logcounts" assay SigDoTS uses
hvg <- getTopHVGs(modelGeneVar(spe), n = 150) # the genes SigDoTS uses
fit <- sigdots(spe, K0 = 5, genes = hvg, verbose = FALSE)
fit
#> SigDoTS: 900 spots, 94 genes
#> Number of domains: 3 (spots per domain: 300, 299, 301)
#>
#> Split tree ([node] spots, candidate domains: decision):
#> [9] 900 spots, candidate domains 1,2,3,4,5: split
#> ├── [5] 300 spots, candidate domain 5 => DOMAIN 1
#> └── [8] 600 spots, candidate domains 1,2,3,4: split
#> ├── [6] 299 spots, candidate domains 3,4: no split => DOMAIN 2
#> │ ├── candidate domain 3 160 spots
#> │ └── candidate domain 4 139 spots
#> └── [7] 301 spots, candidate domains 1,2: no split => DOMAIN 3
#> ├── candidate domain 1 144 spots
#> └── candidate domain 2 157 spots
#>
#> Use summary() for the tests.
spe <- add_domains(spe, fit) # adds colData(spe)$sigdots_domain and $sigdots_candidate_domain
table(colData(spe)$sigdots_domain, sigdots_example$region)
#>
#> 1 2 3
#> 1 0 0 300
#> 2 299 0 0
#> 3 1 300 0Package start-up messages are not shown on this page. With
Bioconductor 3.23 (scuttle 1.22, scran 1.40),
logNormCounts(), modelGeneVar() and
getTopHVGs() print warnings that they, or functions they
use, are deprecated in favour of the newer package scrapper; they still
work, and any other normalisation and gene selection works as well.
For Visium data spatialCoords(spe) holds pixel positions
(pxl_col_in_fullres, pxl_row_in_fullres); any
unit works. A SingleCellExperiment without positions, for
example from zellkonverter::readH5AD() on a Scanpy file,
needs coords =; Scanpy keeps the positions in
obsm["spatial"], which becomes
reducedDim(sce, "spatial").
A counts matrix
# counts: genes x spots, raw; xy: spots x 2, rows in the same order as the columns of counts
x <- sigdots_prepare(counts, n_genes = 150) # log(1 + counts per 10,000), 150 most variable genes
dim(x)
#> [1] 900 150
fit <- sigdots(x, sigdots_example$coords, K0 = 5, verbose = FALSE)
fit
#> SigDoTS: 900 spots, 150 genes
#> Number of domains: 3 (spots per domain: 300, 299, 301)
#>
#> Split tree ([node] spots, candidate domains: decision):
#> [9] 900 spots, candidate domains 1,2,3,4,5: split
#> ├── [5] 300 spots, candidate domain 5 => DOMAIN 1
#> └── [8] 600 spots, candidate domains 1,2,3,4: split
#> ├── [6] 299 spots, candidate domains 3,4: no split => DOMAIN 2
#> │ ├── candidate domain 3 171 spots
#> │ └── candidate domain 4 128 spots
#> └── [7] 301 spots, candidate domains 1,2: no split => DOMAIN 3
#> ├── candidate domain 1 154 spots
#> └── candidate domain 2 147 spots
#>
#> Use summary() for the tests.Notes on the genes
Any normalisation and gene selection can be used; the examples take the most variable genes because that is what the paper did. The genes enter two places: the principal components used for the candidate domains and the tree, and the split statistic, which uses all the genes given. Genes with larger variance weigh more in both; scale the columns first if you want every gene to count equally. Give at least a few hundred genes; the simulated data need a gene covariance to be estimated.
If an expression matrix has one row per gene, SigDoTS stops and tells
you to use t(x).
2. The candidate domains
SigDoTS starts from an over-segmentation and decides which of its candidate domains to merge. It assumes that each candidate domain lies inside one true domain; it can merge candidate domains, but it cannot split one.
With the built-in clustering give K0,
the number of candidate domains, larger than the number of domains you
expect (twice as many is a reasonable start):
fit <- sigdots(x, coords, K0 = 10) # k-means (default)
fit <- sigdots(x, coords, K0 = 10, cluster_method = "banksy") # needs Banksy
fit <- sigdots(x, coords, K0 = 10, cluster_method = "bayesspace") # needs BayesSpaceBANKSY and BayesSpace are Bioconductor packages and are not installed
with SigDoTS; if they are missing, SigDoTS stops and prints the
installation command. Arguments for them go in
cluster_args.
With your own labels (for example from Seurat, Scanpy or a BANKSY run you have already tuned):
fit <- sigdots(x, coords, candidate_labels = my_labels, cluster_method = "kmeans")The tree is built from your labels. The simulated datasets, however,
are still grouped with cluster_method, because SigDoTS must
apply a clustering procedure to them. The test is therefore calibrated
for labels made the way cluster_method makes them; when
your labels come from a very different method, keep this in mind when
you read the p-values.
Size of the parts. Every tested part of the tree
needs enough spots for the spatial parameters to be estimated (on a
regular grid, about 80 or more). With many small candidate domains, the
lower parts of the tree may be too small; SigDoTS then leaves them
untested and warns. A smaller K0 avoids this.
A region of interest. SigDoTS can be run on any
subset of spots, for example one anatomical layer, to ask whether that
layer has substructure. Subset x and coords to
the spots of the region and run as usual.
3. Exact or approximate spatial computation
The simulated datasets need the spots’ spatial correlation matrix, an n x n matrix for a part of the tree with n spots.
-
spatial_method = "vecchia"(default): the Vecchia approximation withvecchia_neighbors = 60neighbours. Memory and time grow roughly linearly with n. -
spatial_method = "exact": the exact matrix and its eigendecomposition. Memory grows with n^2 (about 16 GiB at 20,000 spots) and time faster still. SigDoTS stops before a test whose estimated memory exceedssigdots_control(max_exact_memory_gib = 16); raise it if your machine has more memory.
4. Run time, cores and memory
-
n_coresruns the simulated datasets of a test in parallel (Linux and macOS; on Windows SigDoTS uses one core). The result is the same for any number of cores. - The first test, on all spots, is the slowest; it uses 19 simulated
datasets at
alpha = 0.05.
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). At 50,176 spots the exact computation took 12 hours and 206 GiB; use Vecchia there.
Estimating the spatial parameters uses memory that grows with the square of the number of spots in a part of the tree, whatever the spatial method: measured for one estimate with 200 genes, 0.31 GiB at 2,500 spots, 2.05 GiB at 10,000, 7.42 GiB at 19,881 and 28.99 GiB at 40,000. For very large samples, run SigDoTS on a computer with enough memory, or on a region of interest.
5. Options you will rarely change
sigdots_control() holds the remaining settings; the
defaults are those used in the paper. The most likely to matter:
-
ell_range = c(0.3, 40): the range ofell(in spot spacings) searched. If SigDoTS warns thatellis at the upper end, rerun with a wider range, for examplecontrol = sigdots_control(ell_range = c(0.3, 80)). -
min_node_size = 20,min_child_size = 8: parts or sides smaller than this are not tested. -
B_cap = 5000: the largest number of simulated datasets for one test. A test on very few of very many spots has a tiny level and may need more; SigDoTS then warns.
Other arguments of sigdots(): alpha (0.05),
B_min, B_max (10 and 10), n_pcs
(15), seed (1), and pvalue_method
("monte_carlo", or "normal_adaptive" for a
normal approximation of the p-value that needs fewer simulated datasets;
see ?sigdots).
6. Reading the result
print(fit), summary(fit),
domains(fit) and plot(fit, type = ...) are
explained in vignette("SigDoTS").
add_domains(object, fit) writes the domain of every spot
into a Seurat or SpatialExperiment object; domains(fit)
returns one row per spot in the order of the data for anything else.
For a figure of the domains on the tissue with your own styling, take
domains(fit)$domain and the coordinates and draw them with
ggplot2, or add layers to plot(fit), which is a ggplot
object.
