Skip to contents

The config object — scConf — is the single place you control what the generated app shows and how it looks. It is an ordinary data.table, so you can inspect and edit it directly, but the helpers in this article keep it internally consistent and are the supported route.

The examples below run against the same multimodal PBMC CITE-seq object used in vignette("cellsight"):

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

bfc <- BiocFileCache(ask = FALSE)
pbmc_path <- bfcrpath(bfc, "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!

What is in a config

createConfig() returns one row per cell-metadata column, with these columns:

column meaning
ID the metadata’s name in the object (colnames(seu@meta.data))
UI the label shown in the app
fID factor levels, \|-separated, in object order
fUI the labels shown for those levels, \|-separated
fCL one hex colour per level, \|-separated
fRow how many rows the legend is wrapped onto
default 1 or 2 for the two default metadata, 0 otherwise
grp TRUE if the metadata can group cells (2+ levels)

Most helpers accept either the ID or the UI value for meta.to.mod — they detect which you used. Once you have renamed something with modMetaName(), be consistent about which name you pass afterwards.

Two functions let you look before you edit:

showOrder(scConf)    # a data.frame of ID / UI / levels, in display order

#>      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
showLegend(scConf)   # a ggplot of every legend, with its colours

#> $orig.ident
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $lane
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $donor
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $time
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $celltype.l1
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $celltype.l2
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $Phase
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $continuous
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]

showLegend() is the fastest way to catch a palette that reads badly, and takes fontSize if the labels are long.

Choosing which metadata appears

Restrict at creation time when you already know what you want:

scConf <- createConfig(seu, meta.to.include = c("orig.ident", "celltype.l1", "celltype.l2"))

Or start from everything and prune. delMeta() takes a vector:

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!
scConf <- delMeta(scConf, c("nCount_RNA", "nFeature_RNA", "Phase"))

addMeta() brings a column back, or adds one that createConfig() skipped — note that it needs the object too, since it has to read the column’s levels:

scConf <- addMeta(scConf, "Phase", seu)
scConf <- addMeta(scConf, "celltype.l3", seu, maxLevels = 100)

celltype.l3 is the finest-grained cell-type annotation on this object and has more categories than the default maxLevels (50) allows, so it was dropped by createConfig(); addMeta() lets you bring it in anyway once you raise the limit deliberately. The same guard protects you from accidentally exposing something like a per-cell barcode as a categorical variable.

Renaming for display

modMetaName() changes only the app-facing label, never the underlying column, and is vectorised:

scConf <- modMetaName(
  scConf,
  meta.to.mod = c("orig.ident", "celltype.l1", "nFeature_SCT"),
  new.name    = c("Sample", "Cell type", "RNA features")
)

modLabels() renames the levels within one metadata. Unlike the others it takes exactly one metadata at a time, and new.labels must be in the same order as the existing levels — check with showOrder() first:

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:   orig.ident       Sample   cat.      24       1
#>  4:         lane         lane   cat.      13        
#>  5:        donor        donor   cat.       8        
#>  6:         time         time   cat.       3        
#>  7:  celltype.l1    Cell type   cat.       8        
#>  8:  celltype.l2  celltype.l2   cat.      31        
#>  9:   nCount_SCT   nCount_SCT  cont.       0        
#> 10: nFeature_SCT RNA features  cont.       0        
#> 11:        Phase        Phase   cat.       3        
#> 12:  celltype.l3  celltype.l3   cat.      58

scConf <- modLabels(
  scConf,
  meta.to.mod = "Cell type",
  new.labels  = c("B cells", "CD4 T cells", "CD8 T cells", "Dendritic cells",
                  "Monocytes", "NK cells", "Other", "Other T cells")
)

Colours

modColours() also takes one metadata at a time, with one colour per level in level order. Any format R accepts works — hex codes or named colours:

scConf <- modColours(
  scConf,
  meta.to.mod = "Cell type",
  new.colours = c("#A6CEE3", "#1F78B4", "#B2DF8A", "#33A02C",
                  "#FB9A99", "#E31A1C", "#FDBF6F", "#FF7F00")
)

Colour palettes are a good place to be deliberate: the default is a colorRampPalette() interpolation of a 12-colour Paired-style set, which starts to produce near-indistinguishable neighbours once a metadata has more than roughly a dozen levels. If a cell type matters, give it a colour that survives being one point among 100,000.

For a sequential or a colourblind-safe set, generate rather than hand-pick:

# "Cell type" here is the display name (UI); use the object's column name if
# you have not renamed it. modColours() errors unless the lengths match exactly.
n <- length(strsplit(scConf[UI == "Cell type"]$fID, "\\|")[[1]])
scConf <- modColours(scConf, "Cell type", scales::hue_pal()(n))

Ordering

reorderMeta() sets the order metadata appear in the app’s dropdowns. Unlike the other helpers it accepts only ID values — the object’s column names, not display names — and it needs a complete permutation: every ID present exactly once, or it errors. Read the current set off the config rather than typing it out:

scConf$ID
#>  [1] "nCount_ADT"   "nFeature_ADT" "orig.ident"   "lane"         "donor"       
#>  [6] "time"         "celltype.l1"  "celltype.l2"  "nCount_SCT"   "nFeature_SCT"
#> [11] "Phase"        "celltype.l3"

scConf <- reorderMeta(scConf, c("celltype.l1", "celltype.l2", "celltype.l3",
                                 "orig.ident", "Phase", "lane", "donor", "time",
                                 "nCount_ADT", "nFeature_ADT", "nCount_SCT",
                                 "nFeature_SCT"))

Put the metadata people actually reach for first; the app’s default selections come from default, but the dropdown order is what everyone scrolls through.

Defaults

modDefault() nominates the two metadata the app opens on — the first is used for the main grouping, the second for the side-by-side and split views:

scConf <- modDefault(scConf, default1 = "Cell type", default2 = "orig.ident")

createConfig() guesses these by pattern-matching ident/library for the first and clust for the second, which is often right and worth overriding when it is not. Both must be metadata with grp == TRUE.

Validate before building

checkConfig() re-reads the object and reports every mismatch it finds — metadata that no longer exists, levels that have changed — rather than stopping at the first:

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

Run it after a round of edits, and especially after re-running any upstream analysis that might have changed cluster labels. A config that has drifted from its object produces an app that builds cleanly and then misbehaves.

A worked config

Putting it together, a typical config pass looks like:

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!
scConf <- delMeta(scConf, c("nCount_RNA", "nFeature_RNA", "nCount_SCT", "nFeature_SCT"))
scConf <- modMetaName(scConf, c("orig.ident", "celltype.l1"), c("Sample", "Cell type"))

# one colour per level, in level order
nCellType <- length(strsplit(scConf[UI == "Cell type"]$fID, "\\|")[[1]])
scConf <- modColours(scConf, "Cell type", scales::hue_pal()(nCellType))

# reorderMeta() wants IDs, and all of them
scConf <- reorderMeta(scConf, c("celltype.l1", "celltype.l2", "orig.ident", "Phase",
                                 "lane", "donor", "time", "nCount_ADT", "nFeature_ADT"))
scConf <- modDefault(scConf, "Cell type", "orig.ident")

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

#> $celltype.l1
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $celltype.l2
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $orig.ident
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $Phase
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $lane
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $donor
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $time
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]
#> 
#> $continuous
#> TableGrob (5 x 5) "guide-box": 2 grobs
#>   z     cells                  name           grob
#> 1 1 (3-3,3-3)                guides gtable[layout]
#> 2 0 (2-4,2-4) legend.box.background zeroGrob[NULL]

Then build, as in vignette("cellsight").

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      labeling_0.4.3         filelock_1.0.3        
#>  [43] progressr_1.1.0        spatstat.sparse_3.2-0  httr_1.4.9            
#>  [46] polyclip_1.10-7        abind_1.4-8            compiler_4.4.3        
#>  [49] bit64_4.8.6            withr_3.0.3            S7_0.2.2              
#>  [52] DBI_1.3.0              fastDummies_1.7.6      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          glue_1.8.1            
#>  [61] nlme_3.1-167           promises_1.5.0         Rtsne_0.17            
#>  [64] cluster_2.1.8          reshape2_1.4.5         generics_0.1.4        
#>  [67] gtable_0.3.6           spatstat.data_3.1-9    tzdb_0.5.0            
#>  [70] tidyr_1.3.2            hms_1.1.4              spatstat.geom_3.8-3   
#>  [73] RcppAnnoy_0.0.23       ggrepel_0.9.8          RANN_2.6.3            
#>  [76] pillar_1.11.1          stringr_1.6.0          spam_2.11-4           
#>  [79] RcppHNSW_0.7.0         later_1.4.8            splines_4.4.3         
#>  [82] dplyr_1.2.1            lattice_0.22-6         survival_3.8-3        
#>  [85] bit_4.6.0              deldir_2.0-4           tidyselect_1.2.1      
#>  [88] miniUI_0.1.2           pbapply_1.7-5          knitr_1.52            
#>  [91] charport_0.1.1         scattermore_1.2        xfun_0.62             
#>  [94] matrixStats_1.5.0      stringi_1.8.9          yaml_2.3.12           
#>  [97] evaluate_1.0.5         codetools_0.2-20       tibble_3.3.1          
#> [100] cli_3.6.6              RcppParallel_6.2.1     uwot_0.2.5            
#> [103] xtable_1.8-8           systemfonts_1.3.2      jquerylib_0.1.4       
#> [106] Rcpp_1.1.2             globals_0.20.0         spatstat.random_3.5-2 
#> [109] png_0.1-9              spatstat.univar_3.2-0  parallel_4.4.3        
#> [112] blob_1.3.0             pkgdown_2.1.1          dotCall64_1.2         
#> [115] listenv_1.1.0          viridisLite_0.4.3      scales_1.4.0          
#> [118] ggridges_0.5.7         purrr_1.2.2            rlang_1.3.0           
#> [121] cowplot_1.2.0          qs2_0.4.0