22 CITE-seq with ShinyCell2

Author

Affiliation

Dr Randy Johnson

Hood College

Published

October 8, 2025

Introduction

In today’s hands-on exercise we’ll be playing with an output from ShinyCell2 (Chen et al. 2025; Ouyang 2025). The data comes from a multimodal reference atlas built from a CITE-seq analysis of 211,000 human peripheral blood mononuclear cells (PMBCs) with 228 antibodies from 8 individuals (Hao et al. 2021). This is the same paper that introduced the weighted-nearest neighbor (WNN) analysis approach.

Setup

We’ll be following the instructions from this tutorial for ShinyCell2.

Prepare to run the app

You’ll need to download the app - this is linked in Blackboard under this week’s materials. Once you have it downloaded and saved in a good place:

Open the terminal app (use git-bash on Windows)
Navigate to the location of the file using cd
Unzip with tar -zxf shinyApp_CITE-seq.tar.gz
Open shinyApp_CITE-seq.Rproj within the decompressed folder
Install following R packages:

# packages needed to run the app locally
reqPkg = c("shiny", "shinyhelper", "data.table", "Matrix", "DT", "magrittr", 
           "ggplot2", "ggrepel", "hdf5r", "ggdendro", "gridExtra", "ggpubr")
newPkg = reqPkg[!(reqPkg %in% installed.packages()[,"Package"])]
if(length(newPkg)){install.packages(newPkg)}

Creating the app

In order to create the app used in this lab, you’ll need to install the following R packages. This is optional and not recommended during class as it takes awhile to run. You are welcome to try it out later, though!

# packages needed to build the app
reqPkg = c("data.table", "Matrix", "hdf5r", "reticulate", "R.utils", 
           "ggplot2", "gridExtra", "glue", "readr", "future", "RColorBrewer",
           "Seurat", "devtools")
newPkg = reqPkg[!(reqPkg %in% installed.packages()[,"Package"])]
if(length(newPkg)){install.packages(newPkg)}

We should be ready to install ShinyCell2 and generate the app for today.

# install ShinyCell2
devtools::install_github("the-ouyang-lab/ShinyCell2")

# load required packages
library(Seurat)
library(ShinyCell2)

# get the path to this repository
root <- here::here()

# read sample data (2G download from https://zenodo.org/records/15162323)
seu <- readRDS(file.path(root, "data", "scRNA", "multimodal_pbmc.rds"))

# Configuration
scConf <- createConfig(seu)
scConf <- delMeta(scConf, "lane")

# create shiny files
makeShinyFiles(seu, scConf = scConf, dimred.to.use = "umap", 
    shiny.prefix = "sc1", shiny.dir = "shinyApp_CITE-seq/", 
    default.gene1 = "IRF1", default.gene2 = "GATA2")

# generate shiny app
makeShinyCodes(shiny.prefix = "sc1", 
               shiny.dir = "shinyApp_CITE-seq/", 
               shiny.title = "pbmc_CITE-seq")

This file is much smaller than the raw data, but it is still not trivial. I created a zipped archive that you downloaded in the section above with the following command.

tar -czvf shinyApp_CITE-seq.tar.gz shinyApp_CITE-seq

Running the ShinyCell2 app

Files

When looking in the shinyApp_CITE-seq directory, you’ll see 11 or 12 files.

Data

Most of the files contain gene expression data (sc1assay_ADT.h5 and sc1assay_SCT.h5) or configuration and metadata (sc1*.rds).

summary table provided courtesy of Gemini

File Name	Purpose	Content Description
`assay_SCT.h5`	Single-Cell Transcriptomics Data (e.g., RNA)	Contains the normalized gene expression matrix (e.g., from the SCT assay in Seurat). The large data matrix is stored in HDF5 format on disk for memory efficiency.
`assay_ADT.h5`	Antibody-Derived Tag Data (Protein)	Contains the normalized protein expression matrix (e.g., from the ADT assay in Seurat, common in CITE-seq data). Stored in HDF5 format.
`conf.rds`	Configuration	The ShinyCell configuration object (`scConf`), which stores all customized settings like metadata display names and color palettes.
`meta.rds`	Single-Cell Metadata	The cell-level metadata (e.g., cluster assignments, QC metrics). Stored as a `data.table` for fast access by the app.
`def.rds`	App Defaults	Stores the default settings for the app’s initial state, such as the initial gene, reduced dimension plot, and other UI defaults.
`gene.rds`	Gene/Feature Mapping	Contains the list of genes/features available in your dataset, along with any necessary mapping (e.g., Ensembl ID to gene symbol).
`dimr.rds`	Dimension Reduction	The reduced dimension coordinates (e.g., UMAP_1, UMAP_2, tSNE_1, tSNE_2) for all cells, used to plot the cell positions.

Shiny

There are three R scripts that define the shiny app:

File Name	Purpose
`ui.R`	Contains code for the user interface
`server.R`	Contains code for the server logic
`shunyFunc.R`	Contains helper functions to cut down on R dependencies

R

You’ll also see the shinyApp_CITE-seq.Rproj file, which has some information RStudio uses to track the state of your R project, and perhaps a .Rhistory file, containing the history of recent commands that have been run in this project.

Execution

Assuming you have opened shinyApp_CITE-seq.Rproj, open server.R in RStudio and click the ‘Run App’ button () in the source code panel.

References

Chen, Bei Jun, Yi Yang Lim, Xinyi Yang, Lijin Wang, Owen J L Rackham, and John F Ouyang. 2025. “ShinyCell2: An Extended Library for Simple and Sharable Visualisation of Spatial, Peak-Based and Multi-Omic Single-Cell Data.” Bioinformatics. https://doi.org/10.1101/2025.04.22.650045.

Hao, Yuhan, Stephanie Hao, Erica Andersen-Nissen, William M. Mauck, Shiwei Zheng, Andrew Butler, Maddie J. Lee, et al. 2021. “Integrated Analysis of Multimodal Single-Cell Data.” Cell 184 (13): 3573–3587.e29. https://doi.org/10.1016/j.cell.2021.04.048.

Ouyang, John F. 2025. “ShinyCell2.” The Ouyang Lab. https://github.com/the-ouyang-lab/ShinyCell2.