scplotter to work with spatial CITE-seq data prepared by Giotto¶

The technology. Spatial CITE-seq pairs 10x Visium transcript capture with antibody-derived tags, so the same tissue section yields both a whole-transcriptome readout and a multiplexed surface protein readout. The two modalities describe different things — RNA the state of the cell, protein what it presents on its surface — and the interesting comparisons come from clustering each modality separately and then together.

What this notebook covers. Assembling the object from raw RNA and protein tables with spatial coordinates recovered from the barcode strings, attaching the tissue image, clustering RNA, protein and an integrated view, and plotting all three with scplotter's SpatDimPlot and CellDimPlot.

Data. Human skin from GEO series GSE213264 (RNA and protein matrices plus the H&E section).

Before you run. A Giotto Python environment, and the tissue image in place — without it the plots fall back to a flat background.

Upstream tutorial.

  • https://giottosuite.com/articles/spatial_citeseq_human_skin.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/Giotto_Spatial_CITE-Seq.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/Giotto_Spatial_CITE-Seq"

x <- data.table::fread(file.path(data_path, "GSE213264_RAW/GSM6578065_humanskin_RNA.tsv.gz"))

spatial_coords <- data.frame(cell_ID = x$X)
spatial_coords <- cbind(spatial_coords,
                      stringr::str_split_fixed(spatial_coords$cell_ID,
                                                pattern = "x",
                                                n = 2))
colnames(spatial_coords)[2:3] = c("sdimx", "sdimy")
spatial_coords$sdimx <- as.integer(spatial_coords$sdimx)
spatial_coords$sdimy <- as.integer(spatial_coords$sdimy)
spatial_coords$sdimy <- spatial_coords$sdimy*(-1)

rna_matrix <- data.table::fread(file.path(data_path, "GSE213264_RAW/GSM6578065_humanskin_RNA.tsv.gz"))

rna_matrix <- rna_matrix[rna_matrix$X %in% spatial_coords$cell_ID,]

rna_matrix <- rna_matrix[match(spatial_coords$cell_ID, rna_matrix$X),]

rna_matrix <- t(rna_matrix[,-1])

colnames(rna_matrix) <- spatial_coords$cell_ID

protein_matrix <- data.table::fread(file.path(data_path, "GSE213264_RAW/GSM6578074_humanskin_protein.tsv.gz"))

protein_matrix <- protein_matrix[protein_matrix$X %in% spatial_coords$cell_ID,]

protein_matrix <- protein_matrix[match(spatial_coords$cell_ID, protein_matrix$X),]

protein_matrix <- t(protein_matrix[,-1])

colnames(protein_matrix) <- spatial_coords$cell_ID

my_giotto_object <- createGiottoObject(expression = list(rna = list(raw = rna_matrix),
                                                         protein = list(raw = protein_matrix)),
                                       expression_feat = c("rna", "protein"),
                                       spatial_locs = spatial_coords,
                                       instructions = instructions)

my_giotto_image <- createGiottoImage(gobject = my_giotto_object,
                                     do_manual_adj = TRUE,
                                     scale_factor = 0.5,
                                     mg_object = file.path(data_path, "skin.jpg"),
                                     negative_y = TRUE)

my_giotto_object <- addGiottoImage(gobject = my_giotto_object,
                                   images = list(my_giotto_image),
                                   spat_loc_name = "raw")

force(my_giotto_object)
python already initialized in this session
 active environment : 'giotto_env'
 python version : 3.10

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”
Warning message:
“[createExprObj] param 'expression_matrix_class' is deprecated”
do_manual_adj == TRUE
 Boundaries will be adjusted by given values.

An object of class giotto 
>Active spat_unit:  cell 
>Active feat_type:  rna 
dimensions    : 15486, 1691 (features, cells)
[SUBCELLULAR INFO]
[AGGREGATE INFO]
expression -----------------------
  [cell][rna] raw
  [cell][protein] raw
spatial locations ----------------
  [cell] raw
attached images ------------------
images      : image 


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

SpatDimPlot(my_giotto_object, points_size = 2, points_color_by = "lightblue")
No description has been provided for this image
In [4]:
# RNA
my_giotto_object <- filterGiotto(gobject = my_giotto_object,
                                 spat_unit = "cell",
                                 feat_type = "rna",
                                 expression_threshold = 1,
                                 feat_det_in_min_cells = 1,
                                 min_det_feats_per_cell = 1)
# Protein
my_giotto_object <- filterGiotto(gobject = my_giotto_object,
                                 spat_unit = "cell",
                                 feat_type = "protein",
                                 expression_threshold = 1,
                                 feat_det_in_min_cells = 1,
                                 min_det_feats_per_cell = 1)

# RNA
my_giotto_object <- normalizeGiotto(gobject = my_giotto_object,
                                    spat_unit = "cell",
                                    feat_type = "rna",
                                    norm_methods = "standard",
                                    scalefactor = 10000,
                                    verbose = TRUE)
# Protein
my_giotto_object <- normalizeGiotto(gobject = my_giotto_object,
                                    spat_unit = "cell",
                                    feat_type = "protein",
                                    scalefactor = 6000,
                                    verbose = TRUE)

# RNA
my_giotto_object <- addStatistics(gobject = my_giotto_object,
                                  spat_unit = "cell",
                                  feat_type = "rna")
# Protein
my_giotto_object <- addStatistics(gobject = my_giotto_object,
                                  spat_unit = "cell",
                                  feat_type = "protein",
                                  expression_values = "normalized")

# RNA
my_giotto_object <- runPCA(gobject = my_giotto_object,
                           spat_unit = "cell",
                           feat_type = "rna",
                           expression_values = "normalized",
                           reduction = "cells",
                           name = "rna.pca")
# Protein
my_giotto_object <- runPCA(gobject = my_giotto_object,
                           spat_unit = "cell",
                           feat_type = "protein",
                           expression_values = "normalized",
                           scale_unit = TRUE,
                           center = FALSE,
                           method = "factominer")

# RNA
my_giotto_object <- runUMAP(gobject = my_giotto_object,
                            spat_unit = "cell",
                            feat_type = "rna",
                            expression_values = "normalized",
                            reduction = "cells",
                            dimensions_to_use = 1:10,
                            dim_reduction_name = "rna.pca")
# Protein
my_giotto_object <- runUMAP(gobject = my_giotto_object,
                            spat_unit = "cell",
                            feat_type = "protein",
                            expression_values = "normalized",
                            dimensions_to_use = 1:10)

# RNA
my_giotto_object <- createNearestNetwork(gobject = my_giotto_object,
                                         spat_unit = "cell",
                                         feat_type = "rna",
                                         type = "sNN",
                                         dim_reduction_to_use = "pca",
                                         dim_reduction_name = "rna.pca",
                                         dimensions_to_use = 1:10,
                                         k = 20)
# Protein
my_giotto_object <- createNearestNetwork(gobject = my_giotto_object,
                                         spat_unit = "cell",
                                         feat_type = "protein",
                                         type = "sNN",
                                         name = "protein_sNN.pca",
                                         dimensions_to_use = 1:10,
                                         k = 20)

# RNA
my_giotto_object <- doLeidenCluster(gobject = my_giotto_object,
                                    spat_unit = "cell",
                                    feat_type = "rna",
                                    nn_network_to_use = "sNN",
                                    name = "leiden_clus",
                                    resolution = 1)
# Protein
my_giotto_object <- doLeidenCluster(gobject = my_giotto_object,
                                    spat_unit = "cell",
                                    feat_type = "protein",
                                    nn_network_to_use = "sNN",
                                    network_name = "protein_sNN.pca",
                                    name = "leiden_clus",
                                    resolution = 1)

my_giotto_object@cell_metadata$cell$rna$leiden_clus <- as.character(my_giotto_object@cell_metadata$cell$rna$leiden_clus)
my_giotto_object@cell_metadata$cell$protein$leiden_clus <- as.character(my_giotto_object@cell_metadata$cell$protein$leiden_clus)

my_giotto_object <- createNearestNetwork(gobject = my_giotto_object,
                                         spat_unit = "cell",
                                         feat_type = "rna",
                                         type = "kNN",
                                         dim_reduction_name = "rna.pca",
                                         name = "rna_kNN.pca",
                                         dimensions_to_use = 1:10,
                                         k = 20)
my_giotto_object <- createNearestNetwork(gobject = my_giotto_object,
                                         spat_unit = "cell",
                                         feat_type = "protein",
                                         type = "kNN",
                                         name = "protein_kNN.pca",
                                         dimensions_to_use = 1:10,
                                         k = 20)

my_giotto_object <- runWNN(my_giotto_object,
                        #    modality_1 = "rna",
                        #    modality_2 = "protein",
                        #    pca_name_modality_1 = "rna.pca",
                        #    pca_name_modality_2 = "protein.pca",
                           k = 20)

my_giotto_object <- runIntegratedUMAP(my_giotto_object)
                                    #   modality1 = "rna",
                                    #   modality2 = "protein")

my_giotto_object <- doLeidenCluster(gobject = my_giotto_object,
                                    spat_unit = "cell",
                                    feat_type = "rna",
                                    nn_network_to_use = "kNN",
                                    network_name = "integrated_kNN",
                                    name = "integrated_leiden_clus",
                                    resolution = 0.7)

my_giotto_object <- createSpatialNetwork(gobject = my_giotto_object,
                                         method = "kNN",
                                         k = 6,
                                         maximum_distance_knn = 5,
                                         name = "spatial_network")

rank_spatialfeats <- binSpect(my_giotto_object,
                     bin_method = "rank",
                     calc_hub = TRUE,
                     hub_min_int = 5,
                     spatial_network_name = "spatial_network")
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

Feature type:  rna 
Number of cells removed:  0  out of  1691 
Number of feats removed:  363  out of  15486 
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

Feature type:  protein 
Number of cells removed:  0  out of  1691 
Number of feats removed:  0  out of  283 
first scale feats and then cells

Setting expression [cell][rna] normalized

Setting expression [cell][rna] scaled

Warning message in .rna_standard_normalization(gobject = gobject, raw_expr = raw_expr, :
“Caution: Standard normalization was developed for RNA data 
”
first scale feats and then cells

Setting expression [cell][protein] normalized

Setting expression [cell][protein] scaled

calculating statistics for "normalized" expression

calculating statistics for "normalized" expression

"hvf" was not found in the gene metadata information.
 all genes will be used.

Setting dimension reduction [cell][rna] rna.pca

"hvf" was not found in the gene metadata information.
 all genes will be used.

Registered S3 method overwritten by 'ggtext':
  method                       from    
  element_grob.element_textbox plotthis

Setting dimension reduction [cell][protein] protein.pca

Setting dimension reduction [cell][rna] umap

Setting dimension reduction [cell][protein] protein.umap

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

The NN network name was not specified, default to the
 first: "rna_kNN.pca"

The NN network name was not specified, default to the
 first: "protein_kNN.pca"

Calculating rna-rna distance

Calculating protein-protein distance

Found more than one class "dist" in cache; using the first, from namespace 'BiocGenerics'

Also defined by ‘spam’

Found more than one class "dist" in cache; using the first, from namespace 'BiocGenerics'

Also defined by ‘spam’

Calculating integrated Nearest Neighbors

Creating igraph

Setting nearest neighbor network [cell][rna] integrated_kNN

Calculating integrated UMAP

Setting dimension reduction [cell][rna] integrated.umap

Setting dimension reduction [cell][protein] integrated.umap

Setting spatial network [cell] spatial_network

This is the single parameter version of binSpect

1. matrix binarization complete

2. spatial enrichment test completed

3. (optional) average expression of high
 expressing cells calculated

4. (optional) number of high expressing cells
 calculated

In [5]:
names(my_giotto_object@dimension_reduction$cells$cell$rna)
  1. 'pca'
  2. 'umap'
In [6]:
options(repr.plot.width = 14, repr.plot.height = 7)

p1 <- CellDimPlot(
    my_giotto_object,
    spat_unit = "cell",
    feat_type = "rna",
    reduction = "pca",
    group_by = "leiden_clus",
    label = TRUE,
    title = "RNA PCA")
p2 <- CellDimPlot(
    my_giotto_object,
    spat_unit = "cell",
    feat_type = "protein",
    reduction = "pca",
    label = TRUE,
    group_by = "leiden_clus",
    title = "Protein PCA")

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

p1 <- CellDimPlot(
    my_giotto_object,
    spat_unit = "cell",
    feat_type = "rna",
    reduction = "umap",
    group_by = "leiden_clus",
    label = TRUE,
    title = "RNA UMAP")
p2 <- CellDimPlot(
    my_giotto_object,
    spat_unit = "cell",
    feat_type = "protein",
    reduction = "umap",
    label = TRUE,
    group_by = "leiden_clus",
    title = "Protein UMAP")

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

p1 <- SpatDimPlot(my_giotto_object, image = TRUE, group_by = "leiden_clus",
    title = "RNA Leiden clustering")
p2 <- SpatDimPlot(my_giotto_object, image = TRUE, group_by = "leiden_clus",
    spat_unit = "cell", feat_type = "protein", title = "Protein Leiden clustering")

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

p1 <- SpatDimPlot(my_giotto_object, image = TRUE, group_by = "integrated_leiden_clus",
    title = "Integrated Leiden clustering", points_shape = 21, points_size = 2,
    points_border_color = "grey20")

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

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