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.
Go back to scplotter documentation: https://pwwang.github.io/scplotter/
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
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
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
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.”
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
options(repr.plot.width = 7, repr.plot.height = 6)
SpatFeaturePlot(
visiumHD,
features = "nr_feats",
points_size = 6,
points_shape = 21
)
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
)
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.
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
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
)
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