Skip to contents

CellSight turns a single-cell or spatial object into a self-contained Shiny app. You do not write any Shiny code: you describe what to show in a config object, and CellSight writes both the app’s data files and the app’s source.

The code in this article downloads and processes a real, ~175 MB dataset (cached locally after the first run), so it will run against that dataset rather than one of your own unless you substitute it below. It is a 15,000-cell random subsample of a larger public multimodal PBMC CITE-seq object, kept small enough to render quickly and fit comfortably in CI/CD memory budgets.

The two-step workflow

Every CellSight app is built in two steps, in this order:

  1. makeShinyFiles() reads your object and writes the app’s data into shiny.dir — chunked HDF5 expression matrices plus .qs2.rds files holding the config and cell metadata, all prefixed with shiny.prefix (sc1 by default).
  2. makeShinyCodes() writes the app’s code into the same directory — server.R, ui.R and shinyFunc.R.

The split matters because the data step is the slow one, and because the prefix is what ties the two together. Whatever you pass as shiny.prefix to makeShinyFiles() must be passed again to makeShinyCodes().

A minimal app

Using the multimodal PBMC CITE-seq object (15,000 cells, 228 antibodies):

library(Seurat)
#> Loading required package: SeuratObject
#> Loading required package: sp
#> 
#> Attaching package: 'SeuratObject'
#> The following objects are masked from 'package:base':
#> 
#>     intersect, t
#> v5.6 adds significant improvements in speed and efficiency, particularly for large datasets.
#> For more information, see https://satijalab.org/seurat/articles/announcements.
library(cellsight)
#> Loading required package: data.table
#> Loading required package: Matrix
#> Loading required package: hdf5r
#> Loading required package: reticulate
#> Loading required package: ggplot2
#> Loading required package: gridExtra
#> Loading required package: jinjar
#> Loading required package: readr
#> Loading required package: future
#> Loading required package: future.apply
#> Loading required package: RColorBrewer
#> Loading required package: grid
library(BiocFileCache)
#> Loading required package: dbplyr

# Cached download: fetched once, reused on every subsequent render.
bfc <- BiocFileCache(ask = FALSE)
pbmc_path <- bfcrpath(bfc, "https://github.com/OpenOmics/CellSight/releases/download/datav1.0.0/multimodal_pbmc_subsample.rds")
#> adding rname 'https://github.com/OpenOmics/CellSight/releases/download/datav1.0.0/multimodal_pbmc_subsample.rds'
seu <- readRDS(pbmc_path)

scConf <- createConfig(seu)
#> Warning in createConfig(seu): celltype.l3 is excluded as it has >50 levels!
#> Warning in createConfig(seu): X_index is excluded as it has >50 levels!

makeShinyFiles(seu, scConf, shiny.prefix = "sc1", shiny.dir = "shinyApp/")
#> Assay type: Legacy Assay (Seurat v3/v4)
#> Available slots in assay: SCTModel.list counts data scale.data assay.orig var.features meta.features misc key 
#> Assay type: Legacy Assay (Seurat v3/v4)
#> Available slots in assay: counts data scale.data assay.orig var.features meta.features misc key

makeShinyCodes(
  shiny.title  = "PBMC multiomics",
  shiny.prefix = "sc1",
  shiny.dir    = "shinyApp/"
)

That leaves a complete app in shinyApp/. Open shinyApp/ui.R in RStudio and click Run App, or from the console:

shiny::runApp("shinyApp")

See vignette("deployment") for hosting it somewhere other than your laptop.

The config object

createConfig() inspects your object’s cell metadata and returns a data.table — conventionally called scConf — with one row per metadata column it will expose in the app. It decides which columns are usable, picks a colour palette for each categorical one, and guesses which two should be shown by default.

scConf <- createConfig(seu)
#> Warning in createConfig(seu): celltype.l3 is excluded as it has >50 levels!
#> Warning in createConfig(seu): X_index is excluded as it has >50 levels!
showOrder(scConf)

#>      actual name display name   type nlevels default
#>           <char>       <char> <char>   <num>  <char>
#>  1:   nCount_ADT   nCount_ADT  cont.       0       2
#>  2: nFeature_ADT nFeature_ADT  cont.       0        
#>  3:   nCount_RNA   nCount_RNA  cont.       0        
#>  4: nFeature_RNA nFeature_RNA  cont.       0        
#>  5:   orig.ident   orig.ident   cat.      24       1
#>  6:         lane         lane   cat.      13        
#>  7:        donor        donor   cat.       8        
#>  8:         time         time   cat.       3        
#>  9:  celltype.l1  celltype.l1   cat.       8        
#> 10:  celltype.l2  celltype.l2   cat.      31        
#> 11:        Phase        Phase   cat.       3        
#> 12:   nCount_SCT   nCount_SCT  cont.       0        
#> 13: nFeature_SCT nFeature_SCT  cont.       0

You will usually want to adjust it: rename metadata for display, drop uninteresting columns, fix the colours. That is what the mod* helpers are for, and it is worth doing before you build — see vignette("configuration").

Two arguments are worth knowing up front:

# Only expose specific metadata columns
scConf <- createConfig(seu, meta.to.include = c("orig.ident", "celltype.l1", "celltype.l2"))

# Allow more categories per metadata column (default 50; anything above is dropped)
scConf <- createConfig(seu, maxLevels = 100)
#> Warning in createConfig(seu, maxLevels = 100): X_index is excluded as it has
#> >100 levels!

createConfig() errors if it finds no multi-level metadata at all, since an app with nothing to group cells by would be empty. If you hit that, your object probably has not been clustered yet.

Before building, check the config still matches the object:

checkConfig(scConf, seu)
#> ALL OK! No errors found in CellSight config!

Setting sensible defaults

The app opens on whichever metadata and genes you nominate. Setting these saves every future visitor a few clicks:

scConf <- modDefault(scConf, "celltype.l1", "orig.ident")

makeShinyFiles(
  seu, scConf,
  shiny.prefix      = "sc1",
  shiny.dir         = "shinyApp/",
  default.gene1     = "CD3E",
  default.gene2     = "MS4A1",
  default.multigene = c("CD3E", "MS4A1", "CD14", "NKG7", "PPBP"),
  default.dimred    = "umap"
)
#> Assay type: Legacy Assay (Seurat v3/v4)
#> Available slots in assay: SCTModel.list counts data scale.data assay.orig var.features meta.features misc key 
#> Assay type: Legacy Assay (Seurat v3/v4)
#> Available slots in assay: counts data scale.data assay.orig var.features meta.features misc key

default.dimred is also how you choose between reductions when your object has several; dimred.to.use restricts which ones are written at all.

Beyond gene expression

makeShinyFiles() looks at the object you hand it and writes every modality it finds — spatial images, ATAC coverage, precomputed DEG tables — without you calling anything extra. The details of what triggers each one, and the arguments each needs, are in vignette("modalities").

Several datasets in one app

Pass a vector of prefixes to makeShinyCodes(), one per makeShinyFiles() call, plus a header for each. Each dataset’s tabs are grouped under its own navbar dropdown. This is illustrative — seu1/seu2 stand in for two of your own objects:

makeShinyFiles(seu1, scConf1, shiny.prefix = "sc1", shiny.dir = "shinyApp/")
makeShinyFiles(seu2, scConf2, shiny.prefix = "sc2", shiny.dir = "shinyApp/")

makeShinyCodes(
  shiny.title   = "Two-dataset atlas",
  shiny.prefix  = c("sc1", "sc2"),
  shiny.headers = c("Healthy", "Disease"),
  defPtSiz      = c(1.25, 1.5),
  shiny.dir     = "shinyApp/"
)

shiny.headers is ignored for a single dataset, but its length must match shiny.prefix when you have more than one. defPtSiz takes either one value for all datasets or one per dataset — reach for a smaller value when a dataset has enough cells that the default overplots.

Footnotes and citations

shiny.footnotes accepts either a string or a named list, which is rendered as a formatted citation in the app’s footer:

makeShinyCodes(
  shiny.title = "PBMC multiomics",
  shiny.footnotes = list(
    author  = "Liu X., Ouyang J.F., Rossello F.J. et al.",
    title   = "",
    journal = "Nature",
    volume  = "586",
    page    = "101-107",
    year    = "2020",
    doi     = "10.1038/s41586-020-2734-6",
    link    = "https://www.nature.com/articles/s41586-020-2734-6"
  ),
  shiny.prefix = "sc1",
  shiny.dir    = "shinyApp/"
)

Where to go next

Session info

sessionInfo()
#> R version 4.4.3 (2025-02-28)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.5 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: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] grid      stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] BiocFileCache_2.14.0 dbplyr_2.6.0         cellsight_0.0.1     
#>  [4] RColorBrewer_1.1-3   future.apply_1.21.0  future_1.82.0       
#>  [7] readr_2.2.0          jinjar_0.3.2         gridExtra_2.3.1     
#> [10] ggplot2_4.0.3        reticulate_1.47.0    hdf5r_1.3.16        
#> [13] Matrix_1.7-2         data.table_1.18.6.1  Seurat_5.6.0        
#> [16] SeuratObject_5.4.0   sp_2.2-4            
#> 
#> loaded via a namespace (and not attached):
#>   [1] jsonlite_2.0.0         magrittr_2.0.5         spatstat.utils_3.2-5  
#>   [4] farver_2.1.2           rmarkdown_2.32         fs_1.6.5              
#>   [7] ragg_1.5.2             vctrs_0.7.3            ROCR_1.0-12           
#>  [10] memoise_2.0.1          spatstat.explore_3.8-3 htmltools_0.5.9       
#>  [13] curl_8.1.0             sass_0.4.10            sctransform_0.4.3     
#>  [16] parallelly_1.50.0      KernSmooth_2.23-26     bslib_0.12.0          
#>  [19] htmlwidgets_1.6.4      desc_1.4.3             ica_1.0-3             
#>  [22] plyr_1.8.9             plotly_4.12.1          zoo_1.9-1             
#>  [25] cachem_1.1.0           igraph_2.3.4           mime_0.13             
#>  [28] lifecycle_1.0.5        pkgconfig_2.0.3        R6_2.6.1              
#>  [31] fastmap_1.2.0          fitdistrplus_1.2-6     shiny_1.14.0          
#>  [34] digest_0.6.39          patchwork_1.3.2        tensor_1.5.1          
#>  [37] RSpectra_0.16-2        irlba_2.4.1            RSQLite_3.53.3        
#>  [40] textshaping_1.0.5      filelock_1.0.3         progressr_1.1.0       
#>  [43] spatstat.sparse_3.2-0  httr_1.4.9             polyclip_1.10-7       
#>  [46] abind_1.4-8            compiler_4.4.3         bit64_4.8.6           
#>  [49] withr_3.0.3            S7_0.2.2               DBI_1.3.0             
#>  [52] fastDummies_1.7.6      R.utils_2.13.0         MASS_7.3-64           
#>  [55] tools_4.4.3            lmtest_0.9-40          otel_0.2.0            
#>  [58] httpuv_1.6.17          goftest_1.2-3          R.oo_1.27.1           
#>  [61] glue_1.8.1             R.cache_0.17.0         nlme_3.1-167          
#>  [64] promises_1.5.0         Rtsne_0.17             cluster_2.1.8         
#>  [67] reshape2_1.4.5         generics_0.1.4         gtable_0.3.6          
#>  [70] spatstat.data_3.1-9    tzdb_0.5.0             R.methodsS3_1.8.2     
#>  [73] tidyr_1.3.2            hms_1.1.4              spatstat.geom_3.8-3   
#>  [76] RcppAnnoy_0.0.23       ggrepel_0.9.8          RANN_2.6.3            
#>  [79] pillar_1.11.1          stringr_1.6.0          spam_2.11-4           
#>  [82] RcppHNSW_0.7.0         later_1.4.8            splines_4.4.3         
#>  [85] dplyr_1.2.1            lattice_0.22-6         survival_3.8-3        
#>  [88] bit_4.6.0              deldir_2.0-4           tidyselect_1.2.1      
#>  [91] miniUI_0.1.2           pbapply_1.7-5          knitr_1.52            
#>  [94] charport_0.1.1         scattermore_1.2        xfun_0.62             
#>  [97] matrixStats_1.5.0      stringi_1.8.9          yaml_2.3.12           
#> [100] evaluate_1.0.5         codetools_0.2-20       tibble_3.3.1          
#> [103] cli_3.6.6              RcppParallel_6.2.1     uwot_0.2.5            
#> [106] xtable_1.8-8           systemfonts_1.3.2      styler_1.11.0         
#> [109] jquerylib_0.1.4        Rcpp_1.1.2             globals_0.20.0        
#> [112] spatstat.random_3.5-2  png_0.1-9              spatstat.univar_3.2-0 
#> [115] parallel_4.4.3         blob_1.3.0             pkgdown_2.1.1         
#> [118] dotCall64_1.2          listenv_1.1.0          viridisLite_0.4.3     
#> [121] scales_1.4.0           ggridges_0.5.7         purrr_1.2.2           
#> [124] rlang_1.3.0            cowplot_1.2.0          qs2_0.4.0