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:
-
makeShinyFiles()reads your object and writes the app’s data intoshiny.dir— chunked HDF5 expression matrices plus.qs2.rdsfiles holding the config and cell metadata, all prefixed withshiny.prefix(sc1by default). -
makeShinyCodes()writes the app’s code into the same directory —server.R,ui.RandshinyFunc.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 keydefault.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
-
vignette("configuration")— shape the config: labels, colours, ordering. -
vignette("modalities")— spatial, scATAC-seq, DEG and.h5adinputs. -
vignette("deployment")— run the app somewhere other than your laptop. -
vignette("docker")— the prebuilt container and its helper scripts. -
vignette("templates")— change what the generated app itself contains.
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