scplotter to work with 10x Visium data prepared by Giotto¶

The technology. 10x Genomics Visium captures whole-transcriptome gene expression from a tissue section on barcoded spots roughly 55 um across, so each spot mixes one to a handful of cells. The section is H&E stained before capture, which is why Visium data can be drawn either on the spot coordinates alone or on top of the histology image. Being sequencing-based, Visium is unbiased in which genes it measures, but it trades single-cell resolution for breadth.

What this notebook covers. Building a Giotto object from a Visium folder, quality filtering and normalisation, highly-variable feature selection, PCA/UMAP embedding, Leiden clustering on a spatial Delaunay network, and then the scplotter views that matter for spot data: SpatDimPlot with and without the tissue image, FeatureStatPlot for marker genes, and CellStatPlot for cluster composition.

Data. 10x mouse brain (sagittal), the same section used in the Giotto workshop sessions Visium parts I and II.

Before you run. Giotto needs a Python environment for its Leiden/UMAP calls — point GIOTTO_PYTHON at it and install scplotter with devtools::load_all() as the setup cell does.

Upstream tutorial.

  • https://giotto-suite.github.io/giotto_workshop_2024/visium-part-i.html
  • https://giotto-suite.github.io/giotto_workshop_2024/visium-part-ii.html

Go back to scplotter documentation: https://pwwang.github.io/scplotter/

In [1]:
library(Giotto)

# Ensure Giotto can access a python env
genv_exists <- suppressMessages(checkGiottoEnvironment())
print(genv_exists)

python_path <- Sys.getenv("GIOTTO_PYTHON")
Sys.setenv(RETICULATE_PYTHON = python_path)

invisible(capture.output(suppressMessages(set_giotto_python_path(python_path = python_path))))

# library(scplotter)
devtools::load_all()
Loading required package: GiottoClass

Giotto Suite 4.2.3

[1] TRUE
ℹ Loading scplotter
In [2]:
library(Giotto)

## Set instructions
results_folder <- "data/Adult_Mouse_Brain.results"

instructions <- createGiottoInstructions(
    save_dir = results_folder,
    save_plot = FALSE,
    show_plot = TRUE,
    return_plot = TRUE,
    python_path = python_path
)

## Provide the path to the visium folder
data_path <- "data/Adult_Mouse_Brain"

## Create object directly from the visium folder
visium_brain <- createGiottoVisiumObject(
    visium_dir = data_path,
    expr_data = "raw",
    png_name = "tissue_lowres_image.png",
    gene_column_index = 2,
    instructions = instructions
)

visium_brain$in_tissue <- ifelse(visium_brain$in_tissue == 1, "Yes", "No")
# visium_brain@cell_metadata
python already initialized in this session
 active environment : 'giotto_env'
 python version : 3.10

A structured visium directory will be used

 - found image

 - found scalefactors. attempting automatic alignment for the 'lowres' image


Warning message:
“Some of Giotto's expected python module(s) were not found:
leidenalg, sklearn
(This is fine if python-based functions are not needed)

** Python path used:
"/fslustre/qhs/ext_wang_panwen_mayo_edu/scplotter-giotto/envs/giotto_env/bin/python"”
Warning message:
“[createExprObj] param 'expression_matrix_class' is deprecated”
Getting values from [cell][rna] cell metadata

In [3]:
options(repr.plot.width = 7, repr.plot.height = 6)
# devtools::load_all()

p1 <- SpatDimPlot(visium_brain, image = TRUE, group_by = "in_tissue",
    palette = "Blues",   # alias of points_palette
    alpha = 0.6,   # alias of points_alpha
    shape = 21,  # alias of points_shape
    border_color = "grey80",   # alias of points_border_color
    size = 2  # alias of points_size
)
p1
No description has been provided for this image
In [4]:
metadata <- getCellMetadata(gobject = visium_brain,
                            output = "data.table")

in_tissue_barcodes <- metadata[in_tissue == "Yes"]$cell_ID

visium_brain <- subsetGiotto(gobject = visium_brain,
                             cell_ids = in_tissue_barcodes)

visium_brain_statistics <- addStatistics(gobject = visium_brain,
                                         expression_values = "raw")
calculating statistics for "raw" expression

In [5]:
options(repr.plot.width = 7, repr.plot.height = 8)
# devtools::load_all()

p1 <- SpatFeaturePlot(visium_brain_statistics, features = "nr_feats",
    points_shape = 21, points_size = 2.2, points_border_color = "grey80")
p1
No description has been provided for this image
In [6]:
visium_brain <- filterGiotto(
    gobject = visium_brain,
    expression_threshold = 1,
    feat_det_in_min_cells = 50,
    min_det_feats_per_cell = 1000,
    expression_values = "raw",
    verbose = TRUE
)

visium_brain <- normalizeGiotto(
    gobject = visium_brain,
    scalefactor = 6000,
    verbose = TRUE
)

visium_brain <- addStatistics(gobject = visium_brain)
completed 1: preparation

completed 2: subset expression data

completed 3: subset spatial locations

completed 4: subset cell metadata

completed 5: subset feature metadata

completed 6: subset spatial network(s)

completed 7: subsetted dimension reductions

completed 8: subsetted nearest network(s)

completed 9: subsetted spatial enrichment results

for cell

--> cell found back in polygon layer: cell

completed 10: subsetted spatial information data

Feature type:  rna 
Number of cells removed:  4  out of  2702 
Number of feats removed:  7311  out of  22125 
first scale feats and then cells

Setting expression [cell][rna] normalized

Setting expression [cell][rna] scaled

calculating statistics for "normalized" expression

In [7]:
options(repr.plot.width = 7, repr.plot.height = 8)
# devtools::load_all()

p1 <- SpatFeaturePlot(visium_brain, features = "nr_feats",
    points_shape = 21, points_size = 2.2, points_border_color = "grey80")
p1
No description has been provided for this image
In [8]:
# visium_brain <- calculateHVF(gobject = visium_brain,
#                              method = "cov_loess",
#                              save_plot = TRUE,
#                              default_save_name = "HVFplot_loess")
# visium_brain <- calculateHVF(gobject = visium_brain,
#                              method = "var_p_resid",
#                              save_plot = TRUE,
#                              default_save_name = "HVFplot_pearson")
# visium_brain <- calculateHVF(gobject = visium_brain,
#                              method = "cov_groups",
#                              save_plot = TRUE,
#                              default_save_name = "HVFplot_binned")
In [9]:
visium_brain <- runPCA(gobject = visium_brain)
my_features <- head(getFeatureMetadata(visium_brain,
                                       output = "data.table")$feat_ID,
                                       1000)
visium_brain <- runPCA(gobject = visium_brain,
                       feats_to_use = my_features,
                       name = "custom_pca")
visium_brain <- runUMAP(visium_brain,
                        dimensions_to_use = 1:10)
visium_brain <- runtSNE(gobject = visium_brain,
                        dimensions_to_use = 1:10)
visium_brain <- createNearestNetwork(gobject = visium_brain,
                                     dimensions_to_use = 1:10,
                                     k = 15)
visium_brain <- createNearestNetwork(gobject = visium_brain,
                                     dimensions_to_use = 1:10,
                                     k = 15,
                                     type = "kNN")
visium_brain <- doLeidenCluster(gobject = visium_brain,
                                resolution = 0.4,
                                n_iterations = 1000)
visium_brain <- doLouvainCluster(visium_brain)

visium_brain@cell_metadata$cell$rna$leiden_clus <- as.factor(visium_brain@cell_metadata$cell$rna$leiden_clus)
visium_brain@cell_metadata$cell$rna$louvain_clus <- as.factor(visium_brain@cell_metadata$cell$rna$louvain_clus)
"hvf" was not found in the gene metadata information.
 all genes will be used.

Setting dimension reduction [cell][rna] pca

a custom vector of genes will be used to subset the matrix

Setting dimension reduction [cell][rna] custom_pca

Setting dimension reduction [cell][rna] umap

Setting dimension reduction [cell][rna] tsne

As of Giotto 4.2.3 doLeidenCluster() works via {igraph}
 For the python implementation, use doLeidenClusterPython()
 This message appears once per session.

In [10]:
options(repr.plot.width = 15, repr.plot.height = 4)

p1 <- CellDimPlot(visium_brain, group_by = "leiden_clus")
p2 <- CellDimPlot(visium_brain, group_by = "leiden_clus", reduction = "umap")
p3 <- CellDimPlot(visium_brain, group_by = "leiden_clus", reduction = "tsne")

p1 + p2 + p3
No description has been provided for this image
In [11]:
options(repr.plot.width = 6, repr.plot.height = 5)

CellDimPlot(visium_brain, group_by = "leiden_clus", reduction = "umap", graph = TRUE)
The NN network name was not specified, default to the
 first: "sNN.pca"

No description has been provided for this image
In [12]:
options(repr.plot.width = 8, repr.plot.height = 8)

FeatureStatPlot(
    visium_brain,
    reduction = "umap",
    features = c("Xkr4", "Gm19938", "Slc14a2", "Irx5"),
    bg_cutoff = 0,  # unexpressed (<=0) cells stay grey instead of taking colour
    plot_type = "dim"
)
No description has been provided for this image
In [13]:
visium_brain <- createSpatialNetwork(gobject = visium_brain,
                                     method = "kNN",
                                     k = 6,
                                     maximum_distance_knn = 400,
                                     name = "spatial_network")
Setting spatial network [cell] spatial_network

In [14]:
options(repr.plot.width = 12, repr.plot.height = 6)
devtools::load_all()
p1 <- SpatDimPlot(visium_brain, group_by = "leiden_clus")
p2 <- SpatDimPlot(visium_brain, group_by = "louvain_clus")

p1 + p2
ℹ Loading scplotter
No description has been provided for this image
In [15]:
options(repr.plot.width = 7, repr.plot.height = 8)
# devtools::load_all()

SpatDimPlot(visium_brain, group_by = NULL, graph = "spatial_network", points_edge_color = "black",
    points_edge_size = 0.5, points_size = 0.5)
No description has been provided for this image
In [16]:
x <- sessionInfo()
x <- capture.output(print(x))
# hide the BLAS/LAPACK paths
x <- x[!startsWith(x, "BLAS/LAPACK:")]
cat(paste(x, collapse = "\n"))
Warning message in system("timedatectl", intern = TRUE):
“running command 'timedatectl' had status 1”
R version 4.5.1 (2025-06-13)
Platform: x86_64-pc-linux-gnu
Running under: Rocky Linux 8.10 (Green Obsidian)

Matrix products: default
BLAS:   /usr/lib64/libblas.so.3.8.0 
LAPACK: /usr/lib64/liblapack.so.3.8.0  LAPACK version 3.8.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: UTC
tzcode source: system (glibc)

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] scplotter_0.8.2   testthat_3.3.2    Giotto_4.2.3      GiottoClass_0.5.1

loaded via a namespace (and not attached):
  [1] fs_2.1.0                    matrixStats_1.5.0          
  [3] spatstat.sparse_3.2-0       sf_1.1-2                   
  [5] devtools_2.5.2              httr_1.4.9                 
  [7] RColorBrewer_1.1-3          repr_1.1.7                 
  [9] tools_4.5.1                 sctransform_0.4.3          
 [11] backports_1.5.1             R6_2.6.1                   
 [13] uwot_0.2.5                  withr_3.0.3                
 [15] sp_2.2-3                    gridExtra_2.3.1            
 [17] GiottoUtils_0.2.9           progressr_1.0.0            
 [19] quantreg_6.1                cli_3.6.6                  
 [21] Biobase_2.70.0              textshaping_1.0.5          
 [23] Cairo_1.7-0                 spatstat.explore_3.8-2     
 [25] fastDummies_1.7.6           iNEXT_3.0.2                
 [27] labeling_0.4.3              Seurat_5.5.1               
 [29] S7_0.2.2                    spatstat.data_3.1-9        
 [31] proxy_0.4-29                ggridges_0.5.7             
 [33] pbapply_1.7-5               systemfonts_1.3.2          
 [35] pbdZMQ_0.3-14               dbscan_1.2.6               
 [37] R.utils_2.13.0              stringdist_0.9.17          
 [39] dichromat_2.0-1             parallelly_1.48.0          
 [41] sessioninfo_1.2.4           VGAM_1.1-14                
 [43] rstudioapi_0.19.0           FNN_1.1.4.1                
 [45] generics_0.1.4              shape_1.4.6.1              
 [47] gtools_3.9.5                ica_1.0-3                  
 [49] spatstat.random_3.5-1       dplyr_1.2.1                
 [51] Matrix_1.7-6                S4Vectors_0.48.1           
 [53] abind_1.4-8                 R.methodsS3_1.8.2          
 [55] terra_1.9-1                 lifecycle_1.0.5            
 [57] SummarizedExperiment_1.40.0 SparseArray_1.10.10        
 [59] Rtsne_0.17                  grid_4.5.1                 
 [61] promises_1.5.0              crayon_1.5.3               
 [63] miniUI_0.1.2                lattice_0.23-1             
 [65] beachmat_2.26.0             cowplot_1.2.0              
 [67] magick_2.9.1                pillar_1.11.1              
 [69] GenomicRanges_1.62.1        rjson_0.2.23               
 [71] future.apply_1.20.2         codetools_0.2-20           
 [73] glue_1.8.1                  getPass_0.2-4              
 [75] spatstat.univar_3.2-0       data.table_1.18.6.1        
 [77] vctrs_0.7.3                 png_0.1-9                  
 [79] spam_2.11-4                 gtable_0.3.6               
 [81] assertthat_0.2.1            cachem_1.1.0               
 [83] S4Arrays_1.10.1             mime_0.13                  
 [85] tidygraph_1.3.1             Seqinfo_1.0.0              
 [87] survival_3.8-12             SingleCellExperiment_1.32.0
 [89] units_1.0-1                 bluster_1.20.0             
 [91] ellipsis_0.3.3              scRepertoire_2.2.1         
 [93] fitdistrplus_1.2-6          ROCR_1.0-12                
 [95] nlme_3.1-171                usethis_3.2.1              
 [97] RcppAnnoy_0.0.23            evd_2.3-7.1                
 [99] rprojroot_2.1.1             irlba_2.3.7                
[101] KernSmooth_2.23-27          otel_0.2.0                 
[103] DBI_1.3.0                   plotthis_0.14.1            
[105] colorspace_2.1-3            BiocGenerics_0.56.0        
[107] tidyselect_1.2.1            compiler_4.5.1             
[109] BiocNeighbors_2.4.0         SparseM_1.84-2             
[111] xml2_1.6.0                  desc_1.4.3                 
[113] ggdendro_0.2.0              DelayedArray_0.36.1        
[115] plotly_4.12.1               checkmate_2.3.4            
[117] scales_1.4.0                classInt_0.4-11            
[119] lmtest_0.9-40               rappdirs_0.3.4             
[121] goftest_1.2-3               stringr_1.6.0              
[123] SpatialExperiment_1.20.0    digest_0.6.39              
[125] spatstat.utils_3.2-4        XVector_0.50.0             
[127] htmltools_0.5.9             GiottoVisuals_0.2.15.1     
[129] pkgconfig_2.0.3             base64enc_0.1-6            
[131] MatrixGenerics_1.22.0       fastmap_1.2.0              
[133] rlang_1.3.0                 GlobalOptions_0.1.4        
[135] htmlwidgets_1.6.4           shiny_1.14.0               
[137] farver_2.1.2                zoo_1.9-0                  
[139] jsonlite_2.0.0              BiocParallel_1.44.0        
[141] R.oo_1.27.1                 BiocSingular_1.26.1        
[143] magrittr_2.0.5              dotCall64_1.2              
[145] patchwork_1.3.2             IRkernel_1.3.2             
[147] Rcpp_1.1.2                  evmix_2.12                 
[149] ggnewscale_0.5.2            viridis_0.6.5              
[151] reticulate_1.47.0           truncdist_1.0-2            
[153] stringi_1.8.9               ggalluvial_0.12.6          
[155] ggraph_2.2.2                brio_1.1.5                 
[157] MASS_7.3-66                 plyr_1.8.9                 
[159] pkgbuild_1.4.8              parallel_4.5.1             
[161] listenv_1.0.0               ggrepel_0.9.8              
[163] forcats_1.0.1               deldir_2.0-4               
[165] graphlayouts_1.2.5          IRdisplay_1.1              
[167] splines_4.5.1               gridtext_0.1.6             
[169] tensor_1.5.1                circlize_0.4.18            
[171] colorRamp2_0.1.1            igraph_2.3.3               
[173] uuid_1.2-2                  spatstat.geom_3.8-2        
[175] cubature_2.1.4-1            RcppHNSW_0.7.0             
[177] ScaledMatrix_1.18.0         reshape2_1.4.5             
[179] stats4_4.5.1                pkgload_1.5.3              
[181] evaluate_1.0.5              SeuratObject_5.4.0         
[183] tweenr_2.0.3                httpuv_1.6.17              
[185] MatrixModels_0.5-4          RANN_2.6.3                 
[187] tidyr_1.3.2                 purrr_1.2.2                
[189] polyclip_1.10-7             future_1.75.0              
[191] scattermore_1.2             ggplot2_4.0.3              
[193] ggforce_0.5.0               rsvd_1.0.5                 
[195] xtable_1.8-8                e1071_1.7-17               
[197] RSpectra_0.16-2             later_1.4.8                
[199] class_7.3-24                viridisLite_0.4.3          
[201] ragg_1.5.2                  gsl_2.1-9                  
[203] tibble_3.3.1                memoise_2.0.1              
[205] IRanges_2.44.0              cluster_2.1.8.3            
[207] globals_0.19.1