Skip to contents

CellSight ships container assets under tools/docker/CellSight/. The image bundles the full build stack — Seurat, HDF5, and the libbeato/bwtool binaries that ATAC track plots need — behind a command-line interface, so you can build an app without setting up an R environment.

Reach for it when you want reproducibility, when you are building on a cluster or CI runner, or specifically when you need ATAC track plots, since those native dependencies are the most tedious part of a manual install.

What is in the image

Built on rocker/shiny:4.4.3, with:

file role
Dockerfile image definition
install_packages.R CRAN / Bioconductor dependency bootstrap
git_installs.sh builds the native libbeato and bwtool trackplot binaries
build_cellsight.R the main CLI: Seurat RDS in, app out
seurat_inspector.R audits a Seurat object’s structure
ingest_10x.R preprocesses a 10x Visium HD output directory into a Seurat RDS

The Dockerfile installs CellSight itself from GitHub (remotes::install_github("OpenOmics/CellSight")) and places all three scripts on the PATH at /usr/bin/, marked executable. Each carries a #!/usr/bin/env Rscript shebang, so you can invoke them either way:

docker run --rm cellsight:latest build_cellsight.R --help
docker run --rm cellsight:latest Rscript /usr/bin/build_cellsight.R --help

The examples below use the explicit Rscript form.

Build

cd CellSight/tools/docker/CellSight
docker build -t cellsight:latest .

Expect this to take a while: it compiles the native trackplot dependencies and installs the whole Seurat stack from source.

Publish

Tag and push to whichever registry you use — GHCR shown here. Replace <org-or-user> with your namespace:

docker tag cellsight:latest ghcr.io/<org-or-user>/cellsight:latest
docker push ghcr.io/<org-or-user>/cellsight:latest

Push a version tag alongside latest so a deployed app can be traced back to the image that built it:

docker tag cellsight:latest ghcr.io/<org-or-user>/cellsight:v0.0.1
docker push ghcr.io/<org-or-user>/cellsight:v0.0.1

Build an app with build_cellsight.R

The CLI wraps createConfig(), makeShinyFiles() and makeShinyCodes(). Three arguments are required — the object, the output directory, and the project name that becomes the app title:

docker pull ghcr.io/<org-or-user>/cellsight:latest

docker run --rm -it \
  -v /path/to/input:/input \
  -v /path/to/output:/output \
  ghcr.io/<org-or-user>/cellsight:latest \
  Rscript /usr/bin/build_cellsight.R \
    --obj /input/seurat_obj.rds \
    --outdir /output \
    --proj "My CellSight App"

The remaining options:

flag effect
-j, --obj required. Seurat object saved with saveRDS()
-o, --outdir required. where the app is written
--proj required. project name, used as the app title
-a, --assay comma-delimited assays to keep, e.g. RNA,spatial; all others are dropped
--defred default reduction, which must exist in the object
--markers plain-text file of marker genes, one per line
--cluster_labels metadata column holding cluster labels
--rmmeta comma-delimited metadata columns to drop before building
-l, --maxlevels maximum categories per categorical metadata
--filesonly run makeShinyFiles() only
--codesonly run makeShinyCodes() only
--silent suppress verbose output

--markers and --cluster_labels are all-or-nothing: supplying one without the other is a fatal error.

--defred expects the reduction’s components to be named with a trailing 1 and 2 — for --defred UMAP, the object needs UMAP1 and UMAP2.

--filesonly and --codesonly split the two build stages, which is what you want on a cluster: run the slow data step once as a batch job, then re-run the fast code step whenever you want to change the title or point sizes.

Inspect before you build

build_cellsight.R fails on objects missing the reductions or metadata it expects, and the error arrives after the slow part. seurat_inspector.R prints an audit — assays, reductions, metadata columns, cluster summary, and spatial image/slide structure — so you can catch those first. It takes a path as a positional argument:

docker run --rm -it \
  -v /path/to/output:/output \
  ghcr.io/<org-or-user>/cellsight:latest \
  Rscript /usr/bin/seurat_inspector.R /output/visium_hd_sample_16um.rds

Worth doing routinely for spatial data, where it reports the slide structure that drives the app’s slide selector — see vignette("modalities").

Start from raw 10x Visium HD output

ingest_10x.R takes a 10x output directory through QC, normalisation, PCA, clustering and UMAP, and writes a Seurat .rds plus QC and summary plots — a ready-to-build object:

docker run --rm -it \
  -v /path/to/10x_output:/input \
  -v /path/to/output:/output \
  ghcr.io/<org-or-user>/cellsight:latest \
  Rscript /usr/bin/ingest_10x.R \
    --data-dir /input \
    --outdir /output

It exposes the pipeline’s parameters, so you can tune the run without editing the script: --bin-size and --slice for which Visium HD binning and slice to read, --assay, the QC thresholds --min-features / --max-features / --max-pct-mt, and the analysis parameters --nfeatures-hvg, --npcs and --resolution. --output-rds names the output object and --memory-gb caps memory use.

The defaults are a reasonable starting point, not a substitute for looking at the QC plots it writes — clustering --resolution in particular is a choice about your data, and the value that produces biologically sensible clusters is not knowable in advance.

A full run

Ingest, inspect, then build:

IMG=ghcr.io/<org-or-user>/cellsight:latest
docker run --rm -v /data/visium:/input -v /data/out:/output $IMG \
  Rscript /usr/bin/ingest_10x.R --data-dir /input --outdir /output --bin-size 16

docker run --rm -v /data/out:/output $IMG \
  Rscript /usr/bin/seurat_inspector.R /output/visium_hd_sample_16um.rds

docker run --rm -v /data/out:/output $IMG \
  Rscript /usr/bin/build_cellsight.R \
    --obj /output/visium_hd_sample_16um.rds \
    --outdir /output/shinyApp \
    --proj "Visium HD 16um" \
    --defred UMAP

/data/out/shinyApp is then a complete app directory — see vignette("deployment") for serving it.

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] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.39     desc_1.4.3        R6_2.6.1          fastmap_1.2.0    
#>  [5] xfun_0.62         cachem_1.1.0      knitr_1.52        htmltools_0.5.9  
#>  [9] rmarkdown_2.32    lifecycle_1.0.5   cli_3.6.6         sass_0.4.10      
#> [13] pkgdown_2.1.1     textshaping_1.0.5 jquerylib_0.1.4   systemfonts_1.3.2
#> [17] compiler_4.4.3    tools_4.4.3       ragg_1.5.2        bslib_0.12.0     
#> [21] evaluate_1.0.5    yaml_2.3.12       otel_0.2.0        jsonlite_2.0.0   
#> [25] rlang_1.3.0       fs_1.6.5          htmlwidgets_1.6.4