Getting started with STBench

Introduction

STBench is an R package for comparing normalisation methods in spatial transcriptomics.

Load data

data(spe_example)
data(norm_example)

dim(spe_example)
#> [1]  50 944
names(norm_example)
#> [1] "None"    "SpaNorm"

Quality control

Calculate and visualise QC metrics

We first calculate spot-level metrics, including library size, detected genes and mitochondrial fraction, together with gene-level expression summaries. We inspect their distributions before filtering.

spe <- add_qcs(
  spe_example,
  assay_name = "counts",
  mito_pattern = "^mt-|^MT-"
)

p_qc <- plot_qc(
  spe,
  bins = 45,
  show_density = TRUE,
  theme_name = "classic"
)
p_qc$plot

Explore filtering thresholds

We examine the relationship between possible cutoffs and the proportions of spots and genes removed, without performing any filtering. We use illustrative rather than dataset-specific thresholds.

p_cutoffs <- plot_qc_cutoffs(
  spe,
  library_cutoff = 6.5,
  gene_cutoff = 0.2,
  n_points = 100,
  theme_name = "classic"
)
p_cutoffs$plot

Apply filtering and reassess QC

We remove spots and genes below the selected thresholds. Choose cutoffs appropriate to the dataset.

spe_filtered <- filter_qc(
  spe,
  library_cutoff = 2.5,
  gene_cutoff = 0.2,
  recalculate = TRUE,
  assay_name = "counts",
  mito_pattern = "^mt-|^MT-"
)
plot_qc(spe_filtered, theme_name = "classic")$plot

Apply normalisation methods

The None method provides a log1p-transformed baseline. Method-specific arguments are supplied through params. We execute normalisation on the small dataset; for subsequent comparisons, we use the saved norm_example for a consistent reference.

norm_recomputed <- normalize_spe(
  spe_example,
  methods = c("None", "SpaNorm"),
  params = list(
    spanorm = list(
      sample_p = 0.15,
      df_tps = 6,
      adj_method = "logpac",
      seed = 123
    )
  )
)
norm <- norm_example
lapply(norm, dim)
#> $None
#> [1]  50 944
#> 
#> $SpaNorm
#> [1]  50 944

Compare normalised library sizes

We compare summed normalised expression across spots. The comparison uses the normalisation methods in the example dataset.

p_ls <- plot_library_size_comparison(
  norm,
  methods = names(norm),
  assay_name = "logcounts",
  point_size = 0.5,
  theme_name = "classic"
)
p_ls$plot

UMAP visualisation

We run PCA and UMAP independently for each normalisation method and colour by the available cell-type annotation.

umap_data <- get_umap_data(
  norm,
  methods = names(norm),
  prop_spots = 1,
  seed = 123,
  assay_name = "logcounts",
  n_pcs = 10,
  n_neighbors = 15
)
p_umap <- plot_umap_comparison(
  umap_data,
  colour_by = "cell_type",
  point_size = 1,
  alpha = 0.6,
  ncol = 2,
  theme_name = "classic"
)
p_umap$plot

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] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] STBench_0.99.2 rmarkdown_2.32
#> 
#> loaded via a namespace (and not attached):
#>   [1] gridExtra_2.3.1             rlang_1.3.0                
#>   [3] magrittr_2.0.5              scater_1.41.3              
#>   [5] otel_0.3.0                  matrixStats_1.5.0          
#>   [7] compiler_4.6.2              sccore_1.0.7               
#>   [9] vctrs_0.7.3                 pkgconfig_2.0.3            
#>  [11] SpatialExperiment_1.23.0    fastmap_1.2.0              
#>  [13] magick_2.9.1                XVector_0.53.0             
#>  [15] scuttle_1.23.2              labeling_0.4.3             
#>  [17] ggbeeswarm_0.7.3            purrr_1.2.2                
#>  [19] xfun_0.62                   bluster_1.23.1             
#>  [21] cachem_1.1.0                beachmat_2.29.3            
#>  [23] jsonlite_2.0.0              DelayedArray_0.39.8        
#>  [25] BiocParallel_1.47.0         irlba_2.4.1                
#>  [27] clevr_0.1.2                 parallel_4.6.2             
#>  [29] aricode_1.1.0               cluster_2.1.8.3            
#>  [31] R6_2.6.1                    bslib_0.12.0               
#>  [33] RColorBrewer_1.1-3          limma_3.99.5               
#>  [35] leidenAlg_1.1.8             GenomicRanges_1.65.4       
#>  [37] jquerylib_0.1.4             Rcpp_1.1.2                 
#>  [39] Seqinfo_1.3.2               SummarizedExperiment_1.43.0
#>  [41] knitr_1.52                  Banksy_1.9.6               
#>  [43] FNN_1.1.4.1                 IRanges_2.47.5             
#>  [45] Matrix_1.7-6                splines_4.6.2              
#>  [47] igraph_2.3.4                tidyselect_1.2.1           
#>  [49] abind_1.4-8                 yaml_2.3.12                
#>  [51] viridis_0.6.5               codetools_0.2-20           
#>  [53] lattice_0.23-1              tibble_3.3.1               
#>  [55] Biobase_2.73.2              withr_3.0.3                
#>  [57] S7_1.0.0                    evaluate_1.0.5             
#>  [59] SpaNorm_1.7.17              mclust_6.1.4               
#>  [61] pillar_1.11.1               MatrixGenerics_1.25.0      
#>  [63] stats4_4.6.2                generics_0.1.4             
#>  [65] dbscan_1.3.0                S4Vectors_0.51.10          
#>  [67] ggplot2_4.0.4               sparseMatrixStats_1.25.0   
#>  [69] scales_1.4.0                glue_1.8.1                 
#>  [71] metapod_1.21.1              scatterplot3d_0.3-45       
#>  [73] maketools_1.3.2             tools_4.6.2                
#>  [75] BiocNeighbors_2.7.3         sys_3.4.3                  
#>  [77] data.table_1.18.6.1         RSpectra_0.16-2            
#>  [79] ScaledMatrix_1.21.0         buildtools_1.0.0           
#>  [81] scran_1.41.1                grid_4.6.2                 
#>  [83] tidyr_1.3.2                 edgeR_4.99.16              
#>  [85] colorspace_2.1-4            SingleCellExperiment_1.35.2
#>  [87] patchwork_1.3.2             RcppHungarian_0.3          
#>  [89] beeswarm_0.4.0              BiocSingular_1.29.3        
#>  [91] vipor_0.4.7                 cli_3.6.6                  
#>  [93] rsvd_2.0.0                  Polychrome_1.6.2           
#>  [95] S4Arrays_1.13.3             viridisLite_0.4.3          
#>  [97] dplyr_1.2.1                 uwot_0.2.5                 
#>  [99] gtable_0.3.6                sass_0.5.0                 
#> [101] digest_0.6.39               BiocGenerics_0.59.13       
#> [103] ggrepel_0.9.8               SparseArray_1.13.5         
#> [105] dqrng_0.4.1                 rjson_0.2.23               
#> [107] farver_2.1.2                htmltools_0.5.9            
#> [109] lifecycle_1.0.5             statmod_1.5.2