SpaGER: Seurat Integration Guide

Overview

SpaGER provides seamless integration with Seurat (v4 and v5), the most widely used R package for single-cell analysis. This vignette demonstrates how to use SpaGER with Seurat objects.

Prerequisites

library(SpaGER)

# Check Seurat availability
if (requireNamespace("Seurat", quietly = TRUE)) {
  check_seurat_version()
} else {
  message("Seurat not installed. Code examples shown but not executed.")
}

Basic Workflow with Seurat

Load Your Data

library(Seurat)

# Load your spatial and scRNA-seq Seurat objects
# Example: Visium + scRNA-seq reference
spatial_obj <- readRDS("path/to/spatial_seurat.rds")
scrna_obj <- readRDS("path/to/scrna_seurat.rds")

# Check objects
spatial_obj
scrna_obj

Prepare Data (Optional)

# Ensure data is normalized
spatial_obj <- prepare_seurat(spatial_obj, normalize = TRUE)
scrna_obj <- prepare_seurat(scrna_obj, normalize = TRUE)

Run SpaGE

# Predict unmeasured genes
spatial_obj <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  n_pv = 30,
  n_neighbors = 50,
  assay_name = "SpaGE",  # Name for new assay
  verbose = TRUE
)

# Check the new assay was added
Assays(spatial_obj)

Access Predictions

# Switch to SpaGE assay
DefaultAssay(spatial_obj) <- "SpaGE"

# Get predicted expression matrix
predicted_expr <- GetAssayData(spatial_obj, slot = "data")
dim(predicted_expr)

# View specific genes
head(predicted_expr[c("Gad1", "Slc17a7", "Mbp"), ])

Seurat v4 vs v5

SpaGER automatically detects your Seurat version and uses the appropriate interface:

Feature	Seurat v4	Seurat v5
Data access	`slot` parameter	`layer` parameter
Default slot/layer	“data”	“data”
Assay creation	`CreateAssayObject()`	`CreateAssay5Object()`

Explicit Version Control

# For Seurat v4 (explicit)
spatial_obj <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  slot = "data",        # v4 style
  n_pv = 30
)

# For Seurat v5 (explicit)
spatial_obj <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  layer = "data",       # v5 style
  n_pv = 30
)

Predict Specific Genes

# Define genes of interest
marker_genes <- c(
  "Gad1", "Gad2",           # GABAergic markers
  "Slc17a7", "Slc17a6",     # Glutamatergic markers
  "Mbp", "Plp1",            # Oligodendrocyte markers
  "Aqp4", "Gfap"            # Astrocyte markers
)

# Predict only these genes
spatial_obj <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  genes_to_predict = marker_genes,
  n_pv = 30,
  assay_name = "SpaGE_markers"
)

Return Data Frame Instead

# Don't add to Seurat object, return data frame
predicted_df <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  n_pv = 30,
  add_to_object = FALSE  # Return data frame
)

class(predicted_df)
dim(predicted_df)

Working with Different Assays

# Specify which assay to use from each object
spatial_obj <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  assay_spatial = "Spatial",  # Use Spatial assay
  assay_rna = "RNA",          # Use RNA assay
  n_pv = 30
)

Visualization After Prediction

# Set to predicted assay
DefaultAssay(spatial_obj) <- "SpaGE"

# Spatial feature plot
SpatialFeaturePlot(spatial_obj, features = "Gad1")

# Expression heatmap
DoHeatmap(spatial_obj, features = marker_genes)

# Violin plot
VlnPlot(spatial_obj, features = "Gad1", group.by = "seurat_clusters")

Batch Processing Multiple Gene Sets

# Define gene sets
gene_sets <- list(
  excitatory = c("Slc17a7", "Slc17a6", "Camk2a"),
  inhibitory = c("Gad1", "Gad2", "Slc32a1"),
  glial = c("Mbp", "Gfap", "Aqp4", "Cx3cr1")
)

# Predict all gene sets
# Note: For Seurat objects, process one set at a time
for (set_name in names(gene_sets)) {
  assay_name <- paste0("SpaGE_", set_name)
  spatial_obj <- SpaGE.Seurat(
    spatial_seurat = spatial_obj,
    rna_seurat = scrna_obj,
    genes_to_predict = gene_sets[[set_name]],
    n_pv = 30,
    assay_name = assay_name,
    verbose = FALSE
  )
}

Assays(spatial_obj)

Tips for Best Results

1. Matching Cell Types

Ensure your scRNA-seq reference contains cell types present in your spatial data:

# Check cell type composition
table(scrna_obj$cell_type)

# Optionally subset to relevant cell types
scrna_subset <- subset(scrna_obj, cell_type %in% c("Neuron", "Astrocyte", "Oligodendrocyte"))

2. Gene Filtering

# Filter lowly expressed genes before SpaGE
scrna_obj <- scrna_obj[rowSums(GetAssayData(scrna_obj) > 0) > 50, ]

3. Normalize Consistently

# Use same normalization for both datasets
spatial_obj <- NormalizeData(spatial_obj, normalization.method = "LogNormalize")
scrna_obj <- NormalizeData(scrna_obj, normalization.method = "LogNormalize")

Complete Example Workflow

# 1. Load data
spatial_obj <- LoadSeuratRds("spatial.rds")
scrna_obj <- LoadSeuratRds("scrna.rds")

# 2. Prepare (normalize if needed)
spatial_obj <- prepare_seurat(spatial_obj)
scrna_obj <- prepare_seurat(scrna_obj)

# 3. Define genes to predict
genes <- setdiff(rownames(scrna_obj), rownames(spatial_obj))

# 4. Run SpaGE
spatial_obj <- SpaGE.Seurat(
  spatial_seurat = spatial_obj,
  rna_seurat = scrna_obj,
  genes_to_predict = genes[1:100],  # First 100 unmeasured genes
  n_pv = 30,
  n_neighbors = 50
)

# 5. Visualize
DefaultAssay(spatial_obj) <- "SpaGE"
SpatialFeaturePlot(spatial_obj, features = genes[1:4])

# 6. Save
saveRDS(spatial_obj, "spatial_with_predictions.rds")

Troubleshooting

Common Issues

“No shared genes”: Ensure gene names match between datasets

# Check gene name overlap
shared <- intersect(rownames(spatial_obj), rownames(scrna_obj))
length(shared)

Memory issues: For large datasets, predict genes in batches

# Split genes into batches
all_genes <- setdiff(rownames(scrna_obj), rownames(spatial_obj))
batches <- split(all_genes, ceiling(seq_along(all_genes) / 100))

Slow performance: Reduce n_pv or n_neighbors

# Faster but potentially less accurate
spatial_obj <- SpaGE.Seurat(spatial_obj, scrna_obj, n_pv = 20, n_neighbors = 30)

Session Information

sessionInfo()
#> R version 4.6.0 (2026-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 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.26.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] SpaGER_1.0.0   rmarkdown_2.31
#> 
#> loaded via a namespace (and not attached):
#>   [1] deldir_2.0-4           pbapply_1.7-4          gridExtra_2.3         
#>   [4] rlang_1.2.0            magrittr_2.0.5         RcppAnnoy_0.0.23      
#>   [7] otel_0.2.0             spatstat.geom_3.8-1    matrixStats_1.5.0     
#>  [10] ggridges_0.5.7         compiler_4.6.0         png_0.1-9             
#>  [13] vctrs_0.7.3            reshape2_1.4.5         stringr_1.6.0         
#>  [16] pkgconfig_2.0.3        fastmap_1.2.0          promises_1.5.0        
#>  [19] purrr_1.2.2            xfun_0.59              cachem_1.1.0          
#>  [22] jsonlite_2.0.0         goftest_1.2-3          later_1.4.8           
#>  [25] spatstat.utils_3.2-3   irlba_2.3.7            parallel_4.6.0        
#>  [28] cluster_2.1.8.2        R6_2.6.1               ica_1.0-3             
#>  [31] spatstat.data_3.1-9    bslib_0.11.0           stringi_1.8.7         
#>  [34] RColorBrewer_1.1-3     reticulate_1.46.0      spatstat.univar_3.2-0 
#>  [37] parallelly_1.47.0      lmtest_0.9-40          jquerylib_0.1.4       
#>  [40] scattermore_1.2        Rcpp_1.1.1-1.1         knitr_1.51            
#>  [43] tensor_1.5.1           future.apply_1.20.2    zoo_1.8-15            
#>  [46] sctransform_0.4.3      FNN_1.1.4.1            httpuv_1.6.17         
#>  [49] Matrix_1.7-5           splines_4.6.0          igraph_2.3.2          
#>  [52] tidyselect_1.2.1       abind_1.4-8            yaml_2.3.12           
#>  [55] spatstat.random_3.5-0  codetools_0.2-20       miniUI_0.1.2          
#>  [58] spatstat.explore_3.8-1 listenv_1.0.0          lattice_0.22-9        
#>  [61] tibble_3.3.1           plyr_1.8.9             shiny_1.14.0          
#>  [64] S7_0.2.2               ROCR_1.0-12            evaluate_1.0.5        
#>  [67] Rtsne_0.17             future_1.70.0          fastDummies_1.7.6     
#>  [70] survival_3.8-6         polyclip_1.10-7        fitdistrplus_1.2-6    
#>  [73] pillar_1.11.1          Seurat_5.5.0           KernSmooth_2.23-26    
#>  [76] plotly_4.12.0          generics_0.1.4         RcppHNSW_0.7.0        
#>  [79] sp_2.2-1               ggplot2_4.0.3          scales_1.4.0          
#>  [82] globals_0.19.1         xtable_1.8-8           glue_1.8.1            
#>  [85] lazyeval_0.2.3         maketools_1.3.2        tools_4.6.0           
#>  [88] sys_3.4.3              data.table_1.18.4      RSpectra_0.16-2       
#>  [91] RANN_2.6.2             buildtools_1.0.0       dotCall64_1.2         
#>  [94] cowplot_1.2.0          grid_4.6.0             tidyr_1.3.2           
#>  [97] nlme_3.1-169           patchwork_1.3.2        cli_3.6.6             
#> [100] spatstat.sparse_3.2-0  spam_2.11-4            viridisLite_0.4.3     
#> [103] dplyr_1.2.1            uwot_0.2.4             gtable_0.3.6          
#> [106] sass_0.4.10            digest_0.6.39          progressr_0.19.0      
#> [109] ggrepel_0.9.8          htmlwidgets_1.6.4      SeuratObject_5.4.0    
#> [112] farver_2.1.2           htmltools_0.5.9        lifecycle_1.0.5       
#> [115] httr_1.4.8             mime_0.13              MASS_7.3-65