spiSEE adds spatial panels to iSEE for data at cellular resolution: imaging-based (CosMx, Xenium) and sequencing-based (Visium HD, cell-segmented). The data are a standard SpatialExperiment.
A region selected on an overview map (fields of view for CosMx, single cells for the other platforms) is applied to every panel: spatial plots, quality-control histograms, spatial statistics, spatially variable genes, cellular niches and spatial domains. Heavy analyses run only when the user presses Compute, on the selected region.
This vignette shows how to install the package, runs it on a small CosMx example and lists every panel. The vignette CosMx workflow: the mouse dentate gyrus then goes through a complete analysis of a real dataset: quality control of a whole brain section, cell polygons, niches, spatial domains, statistics and the apps.
A small CosMx dataset ships with SpaceTrooper: one field of view (FOV) of a tumour sample with 905 cells, about 1,000 genes, cell polygons and a cell-type label per cell.
library(spiSEE)
library(SpaceTrooper)
dir <- system.file("extdata", "CosMx_DBKero_Tiny", package = "SpaceTrooper")
spe <- readCosmxSPE(dirName = dir, sampleName = "DBKero")
spe <- spatialPerCellQC(spe)
#> Warning in addPerCellQC(spe, subsets = idxlist, use_altexps = use_altexps): 'addPerCellQC' is deprecated.
#> Use 'scrapper::quickRnaQc.se' instead.
#> See help("Deprecated")
#> Warning in .per_cell_qc_metrics(assay(x, assay.type), subsets = subsets, : 'perCellQCMetrics' is deprecated.
#> Use 'scrapper::computeRnaQcMetrics' instead.
#> See help("Deprecated")
spe <- readAndAddPolygonsToSPE(spe)
labels <- read.delim(file.path(dir, "labels_tiny.tsv"))
spe$cell_type <- factor(labels$label[match(colnames(spe), labels$cell_id)])
spe <- spe[!grepl("^NegPrb", rownames(spe)), ]
spe <- scuttle::logNormCounts(spe)
#> Warning in .library_size_factors(assay(x, assay.type), ...): 'librarySizeFactors' is deprecated.
#> Use 'scrapper::centerSizeFactors' instead.
#> See help("Deprecated")
#> Warning in .local(x, ...): 'normalizeCounts' is deprecated.
#> Use 'scrapper::normalizeCounts' instead.
#> See help("Deprecated")
spe
#> class: SpatialExperiment
#> dim: 1000 904
#> metadata(4): fov_positions fov_dim polygons technology
#> assays(2): counts logcounts
#> rownames(1000): RAMP2 CD83 ... TPI1 ZBTB16
#> rowData names(1): subsets_NegPrb
#> colnames(904): f16_c1 f16_c10 ... f16_c98 f16_c99
#> colData names(46): fov cellID ... cell_type sizeFactor
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : CenterX_global_px CenterY_global_px
#> imgData names(1): sample_idOne call opens the app:
spiSEE() detects the platform from characteristic
colData columns (here CosMx, so regions are selected as FOV
tiles), picks the cell-type column, QC metrics and default genes, and
builds a layout. Two layouts are predefined:
mode = "analysis" (the default) and
mode = "qc", meant for unfiltered data.
SpatialExperiment), or drag a box, then press
Validate. Every spatial panel follows. Clear goes back
to the whole dataset; a second click on a selected tile or cell removes
it. A selection can also be given at launch with
selection =.| Panel | Shows | Main parameters |
|---|---|---|
SpatialMapPanel |
the tissue as FOV tiles (CosMx) or cells; region selection | — |
SpatialPlotPanel |
cells or polygons coloured by an annotation, a QC metric or a gene | ColorBy, UsePolygons,
PointSize |
SpatialQCPanel |
histogram of a QC metric, SpaceTrooper’s outlier fences and the number of flagged cells | Metric, UseFences |
FOVZoomPanel (CosMx) |
the selected FOVs and their cells coloured by a QC metric | ColorBy |
FOVStatsPanel (CosMx) |
boxplots of QC metrics per FOV | — |
SpatialStatsPanel |
spatial statistics, listed below | PlotType, Genes,
LabelCol, K, Alpha |
SVGPanel |
genes ranked by Moran’s I on the region; a click shows the gene in a linked spatial plot | TopN, K,
LinkedPanel |
SpatialNichePanel |
niches, neighbourhood composition and entropy, spatial domains | PlotType, LabelCol,
K, NNiches, Lambda |
The statistics panel offers:
| Statistic | PlotType |
|---|---|
| Spatial neighbour graph (k-NN) | graph_plot |
| Local Moran’s I of one or more genes | localmoran_plot |
| Moran scatter plot | moran_plot |
| Local cluster significance (hot and cold spots) | locclust_plot |
| Join-count statistics of the cell types | joincount_plot |
| Cell-type co-occurrence heatmap | joincount_heatmap_plot |
| L-function of the most frequent cell type | lest_plot |
| L-cross function of the two most frequent cell types | lcross_plot |
Moran’s I and local clusters come from Voyager, the L-functions from spatialFDA.
The niche panel shows:
| Plot | PlotType |
|---|---|
| Niches on tissue | niche_map |
| Niche × cell-type enrichment (heatmap) | niche_heatmap |
| Niche composition (bar) | niche_bar |
| Neighbourhood entropy on tissue | entropy_map |
| Spatial domains on tissue | domain_map |
| Expression clusters on tissue | cluster_map |
| Domains vs expression clusters | domain_vs_cluster |
The analyses behind the niche panel are exported, so they can be run on the whole dataset beforehand and stored with the object. The neighbour graph is built once:
spe <- buildSpatialGraph(spe, k = 15)
spe <- computeNiches(spe, label_col = "cell_type", k = 15, n_niches = 4)
table(spe$niche)
#>
#> N1: BC cells/NK cells
#> 659
#> N2: CAFs/Blood ECs
#> 45
#> N3: Mix BC cells TAMs/Myoepithelial cells
#> 153
#> N4: Blood ECs/CAFs
#> 47Each niche is named after the two cell types most over-represented in it. The composition of each cell’s neighbourhood is kept as a reduced dimension:
comp <- reducedDim(spe, "NicheComposition")
round(sort(colMeans(comp[spe$cell_type == "TAMs", ], na.rm = TRUE),
decreasing = TRUE)[1:4], 2)
#> BC cells CAFs TAMs Blood ECs
#> 0.59 0.17 0.12 0.06Spatial domains cluster expression smoothed over the neighbourhood
(lambda = weight of the neighbourhood,
lambda = 0 gives plain expression clusters, also returned
as expr_cluster). They need a PCA:
pca <- prcomp(t(as.matrix(logcounts(spe))), rank. = 15)
reducedDim(spe, "PCA") <- pca$x
spe <- computeSpatialDomains(spe, k_spatial = 15, lambda = 0.5,
resolution = 0.5)
table(domain = spe$spatial_domain, expression = spe$expr_cluster)
#> expression
#> domain C1 C2 C3 C4 C5
#> D1 103 0 1 0 0
#> D2 0 179 61 100 26
#> D3 0 4 11 94 59
#> D4 1 22 70 23 1
#> D5 18 2 0 0 78
#> D6 0 0 1 5 45The niche panel opens on these stored results without recomputing,
with the same k, number of niches and lambda;
Compute on a selected region reuses the stored
resolution.
Any list of panels can be passed as initial =, including
standard iSEE panels. A non-empty ComputeTrigger computes a
panel when the app opens:
panels <- list(
SpatialMapPanel(),
SpatialPlotPanel(ColorBy = "cell_type", UsePolygons = TRUE),
SpatialQCPanel(Metric = "Area_um"),
SpatialStatsPanel(PlotType = "joincount_heatmap_plot",
LabelCol = "cell_type", K = 15L,
ComputeTrigger = "launch"),
iSEE::ReducedDimensionPlot(Type = "PCA", ColorBy = "Column data",
ColorByColumnData = "niche"))
app <- spiSEE(spe, initial = panels, cache = FALSE)For reports, plotSpatialCells() draws the cells as in
the spatial plot panels, with the same colours, here the niches computed
above:
Spatial plots are cached as images on disk
(spatialCacheDir()), so a view already seen, also after a
restart, opens at once. The cache keeps 1 GB and drops the least
recently used images first. cache = FALSE keeps images in
memory only; this vignette uses it so that it writes nothing to the
user’s folders. clearSpatialCache() empties the folder.
spe <- loadCosmx("cosmx_spe.rds") # a prepared CosMx object
spe <- loadXenium("path/to/xenium/outs") # 10x Xenium bundle
spe <- loadVisiumHD("path/to/segmented_outputs") # Visium HD, cell-segmentedAny SpatialExperiment with spatial coordinates works;
setPlatform() sets how regions are selected when it cannot
be detected. The app shows one sample at a time: with several samples,
choose one with spiSEE(spe, sample = "..."). Entries of
metadata(spe) that the panels use when present (gene
ranking, per-FOV tables, FOV layout) are listed in
?spiSEE.
sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] ggplot2_4.0.4 SpaceTrooper_1.3.3
#> [3] spiSEE_0.99.2 SpatialExperiment_1.23.0
#> [5] iSEE_2.25.1 SingleCellExperiment_1.35.2
#> [7] SummarizedExperiment_1.43.0 Biobase_2.73.2
#> [9] GenomicRanges_1.65.4 Seqinfo_1.3.2
#> [11] IRanges_2.47.5 S4Vectors_0.51.10
#> [13] BiocGenerics_0.59.13 generics_0.1.4
#> [15] MatrixGenerics_1.25.0 matrixStats_1.5.0
#> [17] BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] fs_2.1.0 spatialreg_1.4-3
#> [3] bitops_1.1-0 sf_1.1-3
#> [5] fontawesome_0.5.3 EBImage_4.55.2
#> [7] httr_1.4.9 RColorBrewer_1.1-3
#> [9] doParallel_1.0.17 tools_4.6.2
#> [11] backports_1.5.1 R6_2.6.1
#> [13] DT_0.34.0 HDF5Array_1.41.7
#> [15] OSTA.data_1.5.0 mgcv_1.9-5
#> [17] rhdf5filters_1.25.5 GetoptLong_1.1.1
#> [19] withr_3.0.3 sp_2.2-4
#> [21] gridExtra_2.3.1 textshaping_1.0.5
#> [23] cli_3.6.6 shinyjs_2.1.1
#> [25] sandwich_3.1-3 labeling_0.4.3
#> [27] marginaleffects_1.0.0 sass_0.4.10
#> [29] mvtnorm_1.4-2 arrow_26.0.1
#> [31] S7_0.2.2 robustbase_0.99-7
#> [33] proxy_0.4-29 systemfonts_1.3.3
#> [35] svglite_2.2.2 R.utils_2.13.0
#> [37] dichromat_2.0-1 scater_1.41.3
#> [39] maps_3.4.4 limma_3.99.5
#> [41] pals_1.10 httpcode_0.3.0
#> [43] RSQLite_3.53.3 shape_1.4.6.1
#> [45] car_3.1-5 spdep_1.4-2
#> [47] dplyr_1.2.1 Matrix_1.7-6
#> [49] ggbeeswarm_0.7.3 abind_1.4-8
#> [51] R.methodsS3_1.8.2 terra_1.9-50
#> [53] lifecycle_1.0.5 multcomp_1.4-32
#> [55] yaml_2.3.12 edgeR_4.99.13
#> [57] carData_3.0-6 rhdf5_2.57.20
#> [59] SparseArray_1.13.5 BiocFileCache_3.3.3
#> [61] blob_1.3.0 grid_4.6.2
#> [63] promises_1.5.0 dqrng_0.4.1
#> [65] crayon_1.5.3 shinydashboard_0.7.3
#> [67] miniUI_0.1.2 lattice_0.23-1
#> [69] beachmat_2.29.3 cowplot_1.2.0
#> [71] mapproj_1.2.12 magick_2.9.1
#> [73] sys_3.4.3 maketools_1.3.2
#> [75] zeallot_0.2.0 pillar_1.11.1
#> [77] knitr_1.52 ComplexHeatmap_2.29.0
#> [79] osfr_0.2.9 rjson_0.2.23
#> [81] boot_1.3-32 codetools_0.2-20
#> [83] wk_0.9.5 glue_1.8.1
#> [85] data.table_1.18.6.1 urltools_1.7.3.1
#> [87] vctrs_0.7.3 png_0.1-9
#> [89] gtable_0.3.6 assertthat_0.2.1
#> [91] cachem_1.1.0 xfun_0.62
#> [93] S4Arrays_1.13.2 mime_0.13
#> [95] DropletUtils_1.33.2 coda_0.19-4.1
#> [97] survival_3.8-12 pheatmap_1.0.13
#> [99] sfheaders_0.4.5 iterators_1.0.14
#> [101] units_1.0-1 statmod_1.5.2
#> [103] TH.data_1.1-5 nlme_3.1-172
#> [105] bit64_4.8.6 filelock_1.0.3
#> [107] bslib_0.12.0 irlba_2.4.1
#> [109] vipor_0.4.7 KernSmooth_2.23-27
#> [111] otel_0.3.0 colorspace_2.1-4
#> [113] spData_2.3.5 DBI_1.3.0
#> [115] tidyselect_1.2.1 curl_8.1.0
#> [117] bit_4.6.0 compiler_4.6.2
#> [119] SpatialFeatureExperiment_1.15.1 httr2_1.3.0
#> [121] glmnet_5.2 BiocNeighbors_2.7.3
#> [123] h5mread_1.5.7 DelayedArray_0.39.8
#> [125] triebeard_0.4.1 colourpicker_1.3.0
#> [127] scales_1.4.0 DEoptimR_1.2-2
#> [129] classInt_0.4-11 tiff_0.1-12
#> [131] digest_0.6.39 fftwtools_0.9-11
#> [133] rmarkdown_2.32 XVector_0.53.0
#> [135] htmltools_0.5.9 pkgconfig_2.0.3
#> [137] jpeg_0.1-11 sparseMatrixStats_1.25.0
#> [139] dbplyr_2.6.0 listviewer_4.0.0
#> [141] fastmap_1.2.0 rlang_1.3.0
#> [143] GlobalOptions_0.1.4 htmlwidgets_1.6.4
#> [145] shiny_1.14.0 DelayedMatrixStats_1.35.0
#> [147] farver_2.1.2 jquerylib_0.1.4
#> [149] zoo_1.9-1 jsonlite_2.0.0
#> [151] BiocParallel_1.47.0 R.oo_1.27.1
#> [153] BiocSingular_1.29.3 RCurl_1.98-1.20
#> [155] magrittr_2.0.5 Formula_1.2-6
#> [157] scuttle_1.23.2 s2_1.1.13
#> [159] Rhdf5lib_2.1.0 Rcpp_1.1.2
#> [161] viridis_0.6.5 stringi_1.8.9
#> [163] rintrojs_0.3.4 MASS_7.3-66
#> [165] parallel_4.6.2 ggrepel_0.9.8
#> [167] deldir_2.0-4 splines_4.6.2
#> [169] circlize_0.4.18 locfit_1.5-9.12
#> [171] igraph_2.3.4 ggpubr_1.0.0
#> [173] ggsignif_0.6.4 buildtools_1.0.0
#> [175] ScaledMatrix_1.21.0 LearnBayes_2.15.2
#> [177] crul_1.6.0 evaluate_1.0.5
#> [179] BiocManager_1.30.27 foreach_1.5.2
#> [181] httpuv_1.6.17 tidyr_1.3.2
#> [183] purrr_1.2.2 clue_0.3-68
#> [185] rsvd_2.0.0 broom_1.0.13
#> [187] xtable_1.8-8 SpatialExperimentIO_1.5.0
#> [189] e1071_1.7-17 rstatix_1.1.0
#> [191] later_1.4.8 viridisLite_0.4.3
#> [193] class_7.3-24 tibble_3.3.1
#> [195] memoise_2.0.1 beeswarm_0.4.0
#> [197] cluster_2.1.8.3 shinyWidgets_0.9.1
#> [199] shinyAce_0.4.4