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

The technology. Visium HD uses the same Visium chemistry but with a continuous lawn of 2 um barcoded squares instead of 55 um spots. Because a 2 um square holds no usable counts on its own, the data is aggregated into 8 um or 16 um bins that approximate single cells. The result is whole-transcriptome sequencing data at a resolution much closer to imaging-based platforms.

What this notebook covers. Reading a Visium HD object, aggregating 2 um bins into 8 um bins with aggregateFeatures(), embedding and clustering, and visualising bins with scplotter's spatial layers — including how bin resolution changes what a SpatDimPlot looks like.

Data. The 10x Visium HD colorectal cancer section used in the Giotto workshop Visium HD session.

Before you run. A Giotto Python environment (GIOTTO_PYTHON), and enough memory for the bin-level object — HD objects are large before aggregation.

Upstream tutorial.

  • https://giotto-suite.github.io/giotto_workshop_2024/visium-hd.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/Human_Colorectal_Cancer_workshop.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/Human_Colorectal_Cancer_workshop/square_002um"

expression_path <- file.path(data_path, 'raw_feature_bc_matrix')
expr_results <- get10Xmatrix(path_to_data = expression_path,
                             gene_column_index = 1)

tissue_positions_path <- file.path(data_path, 'spatial/tissue_positions.parquet')
tissue_positions <- data.table::as.data.table(arrow::read_parquet(tissue_positions_path))

matrix_tile_dt <- data.table::as.data.table(Matrix::summary(expr_results))
genes   <- expr_results@Dimnames[[1]]
samples <- expr_results@Dimnames[[2]]
matrix_tile_dt[, gene := genes[i]]
matrix_tile_dt[, pixel := samples[j]]

expr_pos_data <- data.table::merge.data.table(matrix_tile_dt,
                                             tissue_positions,
                                             by.x = 'pixel',
                                             by.y = 'barcode')

expr_pos_data <- expr_pos_data[,.(pixel, pxl_row_in_fullres, pxl_col_in_fullres, gene, x)]
colnames(expr_pos_data) = c('pixel', 'x', 'y', 'gene', 'count')

giotto_points = createGiottoPoints(x = expr_pos_data[,.(x, y, gene, pixel, count)])

hexbin400 <- tessellate(extent = ext(giotto_points),
                        shape = 'hexagon',
                        shape_size = 400,
                        name = 'hex400')

# gpoints provides spatial gene expression information
# gpolygons provides spatial unit information (here = hexagon tiles)
visiumHD = createGiottoObjectSubcellular(gpoints = list('rna' = giotto_points),
                                         gpolygons = list('hex400' = hexbin400),
                                         instructions = instructions)

# create spatial centroids for each spatial unit (hexagon)
visiumHD = addSpatialCentroidLocations(gobject = visiumHD,
                                       poly_info = 'hex400')

visiumHD
python already initialized in this session
 active environment : 'giotto_env'
 python version : 3.10

Warning message:
“Potentially unsafe or invalid elements have been discarded from R metadata.
ℹ Type: "externalptr"
→ If you trust the source, you can set `options(arrow.unsafe_metadata = TRUE)` to preserve them.”
  Selecting col "gene" as feat_ID column

  Selecting cols "x" and "y" as x and y respectively

367 polygons generated

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"”
polygonlist is a list with names

[ hex400 ] Process polygon info...

pointslist is a named list

[ rna ] Process point info...

Start centroid calculation for polygon information
 layer: hex400

An object of class giotto 
[SUBCELLULAR INFO]
polygons      : hex400 
features      : rna 
[AGGREGATE INFO]
spatial locations ----------------
  [hex400] raw


Use objHistory() to see steps and params used
In [3]:
options(repr.plot.width = 14, repr.plot.height = 6)
# devtools::load_all()

p1 <- SpatDimPlot(
    visiumHD,
    image = "black",
    shapes = TRUE,
    features = GiottoClass::featIDs(visiumHD, 'rna')[1:20],
    spat_unit = 'hex400',
    shapes_feat_type = 'hex400',
    shapes_border_size = 0.1,
    shapes_border_color = "white",
    shapes_fill_by = "black",
    shapes_alpha = 0.5,
    points_size = 0.25
)
p2 <- SpatDimPlot(
    visiumHD,
    image = "black",
    shapes = TRUE,
    features = GiottoClass::featIDs(visiumHD, 'rna')[1:20],
    spat_unit = 'hex400',
    shapes_feat_type = 'hex400',
    shapes_border_size = 0.1,
    shapes_border_color = "white",
    shapes_fill_by = "black",
    shapes_alpha = 0.5,
    points_size = 0.25,
    raster = TRUE
)
p1 + p2
No description has been provided for this image
In [4]:
visiumHD = calculateOverlap(visiumHD,
                            spatial_info = 'hex400',
                            feat_info = 'rna')
# convert overlap results to bin by gene matrix
visiumHD = overlapToMatrix(visiumHD,
                           poly_info = 'hex400',
                           feat_info = 'rna',
                           name = 'raw')

# this action will automatically create an active spatial unit, ie. hexbin 400
activeSpatUnit(visiumHD)

# filter on gene expression matrix
visiumHD <- filterGiotto(visiumHD,
                         expression_threshold = 1,
                         feat_det_in_min_cells = 5,
                         min_det_feats_per_cell = 25)

# normalize and scale gene expression data
visiumHD <- normalizeGiotto(visiumHD,
                            scalefactor = 1000,
                            verbose = T)

# add cell and gene statistics
visiumHD <- addStatistics(visiumHD)
Warning message:
“The `spatial_info` argument of `calculateOverlap()` is deprecated as of
GiottoClass 0.4.7.
ℹ Please use the `spat_info` argument instead.”
[overlap] Found column "count" in feature info.
 - Using as `feat_count_column`
 [!] Set feat_count_column = FALSE to disable.

Warning message:
“The `poly_info` argument of `overlapToMatrix()` is deprecated as of GiottoClass
0.4.7.
ℹ Please use the `spat_info` argument instead.”
'hex400'
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 hex400

--> hex400 found back in polygon layer: hex400

completed 10: subsetted spatial information data

subset feature info: rna

completed 11: subsetted spatial feature data

Feature type:  rna 
Number of cells removed:  0  out of  367 
Number of feats removed:  349  out of  4967 
first scale feats and then cells

Setting expression [hex400][rna] normalized

Setting expression [hex400][rna] scaled

calculating statistics for "normalized" expression

In [5]:
options(repr.plot.width = 7, repr.plot.height = 6)

SpatFeaturePlot(
    visiumHD,
    features = "nr_feats",
    points_size = 6,
    points_shape = 21
)
No description has been provided for this image
In [6]:
options(repr.plot.width = 7, repr.plot.height = 6)

SpatFeaturePlot(
    visiumHD,
    image = "black",
    shapes = TRUE,
    spat_unit = 'hex400',
    use_overlap = TRUE,
    shapes_fill_by = "nr_feats",
    shapes_feat_type = 'hex400',
    points_size = 0.1
)
No description has been provided for this image
In [7]:
visiumHD <- calculateHVF(visiumHD,
                         zscore_threshold = 1)
visiumHD <- runPCA(visiumHD,
                   expression_values = 'normalized',
                   feats_to_use = 'hvf')
visiumHD <- runUMAP(visiumHD,
                    dimensions_to_use = 1:14,
                    n_threads = 10)
# sNN network (default)
visiumHD <- createNearestNetwork(visiumHD,
                                 dimensions_to_use = 1:14,
                                 k = 5)

## leiden clustering ####
visiumHD <- doLeidenClusterIgraph(visiumHD, resolution = 0.5, n_iterations = 1000, spat_unit = 'hex400')
"hvf" column was found in the feats metadata information and will be
 used to select highly variable features

Setting dimension reduction [hex400][rna] pca

Setting dimension reduction [hex400][rna] umap

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

In [8]:
options(repr.plot.width = 11, repr.plot.height = 5)

p1 <- CellDimPlot(visiumHD, group_by = "leiden_clus", label = TRUE)
p2 <- CellDimPlot(visiumHD, group_by = "leiden_clus", reduction = "umap", label = TRUE)

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

visiumHD@cell_metadata$hex400$rna$leiden_clus <- as.factor(visiumHD@cell_metadata$hex400$rna$leiden_clus)

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