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