Get started with spiSEE

Introduction

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.

Installation

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("spiSEE")

Quick start

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_id

One call opens the app:

app <- spiSEE(spe, cache = FALSE)
if (interactive()) shiny::runApp(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.

getPlatform(spe)
#> [1] "cosmx"

How the app works

  • Select a region on the overview map: click FOV tiles (CosMx) or single cells (Xenium, Visium HD and any other 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 =.
  • Compute when ready: statistics, gene rankings and niches recompute only when Compute is pressed, on the current region and parameters. Results computed beforehand and stored in the object (niches, domains) are shown at once.
  • Combine freely: the spatial panels work next to any iSEE panel (reduced dimensions, feature assays, tables), and Organize panels adds or removes panels while the app runs.

The panels

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

Niches and spatial domains outside the app

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 
#>                                        47

Each 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.06

Spatial 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  45

The 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.

Custom layouts

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:

plotSpatialCells(spe, "niche")
The niches of the example, drawn outside the app with plotSpatialCells().
The niches of the example, drawn outside the app with plotSpatialCells().

Image cache

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.

Loading other data

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-segmented

Any 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.

Session information

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