Pre-course setup guide

Get ready for the workshop

Complete all steps below before the course day.
Virtual machine: 30-60 min download. Local install: 20-40 min, depending on your connection.

Seurat v5 R 4.3+ GSE149689 RNA + ADT 3,000 cells
Before the course

Your pre-course checklist

Tick each item as you complete it. All five must be done before the workshop starts.

Pre-course checklist
Before the course day If any step fails, post a message in Google Classroom with the full error message. Do not leave it for the day of the workshop.
Step 1

Choose your environment

There are two ways to get a working setup for the course. Pick one before doing anything else below — the rest of this guide branches depending on which you choose.

Path A Recommended for most

Virtual machine

A ready-to-use Ubuntu 24.04 virtual machine with RStudio, the dataset, and every package from Block 0 already installed. Best if you do not normally use R, or do not want to troubleshoot installation issues on your own machine.

Download link: posted in Google Classroom (Drive)
Disk: ~8 GB · Runs on Windows, Mac, Linux
Path B

Local install

Install R, RStudio, and the packages directly on your own computer. Faster to run during the course (no virtualization overhead) and better if your computer has limited RAM.

Steps 2 to 5 below · 20-40 min total
Which one should I use?
A You don't know R/RStudio well, or just want everything to work without configuring anything: use the virtual machine. Skip straight to Step 1A below, then go to the checklist.
! Your computer has less than 8 GB of total RAM: use the local install (Path B) instead. A virtual machine needs RAM set aside for the guest Ubuntu system on top of whatever your own OS and other apps are using. On an 8 GB host, the VM alone will struggle, and the course's single-cell steps (PCA, clustering, plotting) will be slow or may run out of memory.
B You already have R/RStudio set up, or you're comfortable installing packages: use the local install (Path B). It will generate the course's plots faster than the VM on the same hardware.
1A
Path A — Download and run the virtual machine
Ubuntu 24.04 · RStudio + packages + dataset pre-installed
▼

Download link: [link to be posted in Google Classroom / shared Drive folder]. The file is a virtual machine image (~8 GB). You will need virtualization software installed first — VirtualBox (free) works on Windows, Mac, and Linux.

What is already done for you The virtual machine runs Ubuntu 24.04 with RStudio installed, every package from Block 0 already installed (Seurat 5.x and the rest — see the package list in Step 4 below), and the course dataset already saved at data/gse149689_subset_3k.rds. You open RStudio inside the VM and the course notebook is ready to run.
1. Install VirtualBox
Download from virtualbox.org for your OS (Windows, Mac, or Linux) and install it with default settings.
2. Import the VM image
Open VirtualBox, choose File > Import Appliance, and select the downloaded file. Keep the default RAM/CPU allocation unless your machine is constrained — see the note below.

Why it shows as "Ubuntu" if you don't know Linux: Ubuntu here is just the operating system that RStudio runs inside. You will only interact with RStudio, the same way you would on Windows or Mac. You do not need to know any Linux commands for this course.

It is all installed — so why could it be slow? Every package and the dataset are already there, so you skip the install step entirely. But during the course, generating plots (PCA, UMAP, clustering, the WNN steps in Block 4) still runs real computation inside the VM. How fast that is depends entirely on the RAM and CPU cores your host computer can spare for the VM — not on anything left to install. A machine with more RAM and cores available will render the course's graphics noticeably faster.

Fixing a low-resolution / cropped screen

If the VM window opens with a small or oddly cropped resolution, the screen-resolution button on the VM window toolbar does not always switch it directly. Change it from the settings menu instead:

Before starting the VM
In VirtualBox, select the VM, click Settings > Display, and increase Video Memory if the option to change resolution later is greyed out.
While the VM is running
Inside Ubuntu, go to Settings > Displays (the gear icon, not the VirtualBox window controls) and pick a resolution that matches your screen.

Changing RAM and CPU cores allocated to the VM

The VM only runs as fast as the resources you give it. To change how much RAM or how many CPU cores it can use:

Where to change it Shut down the VM completely first (it cannot be resized while running). In VirtualBox, select the VM in the list, click Settings, go to System > Motherboard to change RAM, and System > Processor to change the number of CPU cores. As a rule of thumb, leave at least 2-4 GB of RAM and one CPU core free for your own host operating system.
If your computer has less than 8 GB of RAM Do not increase the VM's RAM beyond what your host can spare, and consider using the local install (Path B) instead — see the decision box above. Running the VM on a tight RAM budget will make every step that produces a plot noticeably slower, regardless of how the allocation is tuned.
Step 2 · Path B, local install

Install R

Skip this entire section if you are using the virtual machine from Step 1A.

2
Download and install R 4.3+
https://cran.r-project.org
▼

Go to cran.r-project.org and choose your operating system.

Windows
Click Download R for Windows, then base, then download the installer. Run it with default settings.
Mac
Click Download R for macOS. Choose the version for your chip: Apple Silicon (M1/M2/M3) or Intel.

After installation, open R and confirm the version:

R console 
R.version$major   # should print "4" or higher
R.version$minor   # should print "3.0" or higher
Mac with Apple Silicon (M1/M2/M3) Download the ARM64 version. Using the Intel version on Apple Silicon causes compilation errors when installing packages like Seurat.
Step 3 · Path B, local install

Install RStudio

3
Download RStudio Desktop
https://posit.co/download/rstudio-desktop
▼

Go to posit.co/download/rstudio-desktop and download the free Desktop version for your system.

Alternative: Posit Cloud (no installation needed) If you prefer not to install locally, create a free account at posit.cloud. Create a New Project and upload the course notebook file. The free tier (1 GB RAM) is sufficient for this workshop.

Once installed, open RStudio. You should see four panels: Source (top left), Console (bottom left), Environment (top right), Files (bottom right).

Always start with a clean session on the course day Go to Tools > Global Options > General and set "Save workspace to .RData on exit" to Never. This prevents old results from interfering with a fresh run.
Step 4 · Path B, local install

Install required packages

Skip this entire section if you are using the virtual machine — every package below is already installed there.

Copy the code below into your RStudio console and run it. The first run may take 15 to 30 minutes depending on your connection. Packages that are already installed will be skipped automatically.

4
Run the install script
Installs from CRAN and Bioconductor with automatic fallback
▼
This list matches Block 0 of the course notebook exactly 14 packages, including SingleCellExperiment, needed by the doublet-detection step (scDblFinder) in Block 2. If you installed packages before from an older version of this guide, re-run the script below — it skips anything already installed and only adds what is missing.
R — paste into console 
if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

all_pkgs <- c(
  "Seurat", "SeuratObject", "ggplot2", "patchwork",
  "dplyr", "Matrix", "harmony", "scales", "ggrepel",
  "SingleR", "celldex", "BiocParallel", "scDblFinder",
  "SingleCellExperiment"
)

for (pkg in all_pkgs) {
  if (!requireNamespace(pkg, quietly = TRUE)) {
    message("Installing: ", pkg)
    tryCatch(install.packages(pkg, quiet = TRUE),
             error = function(e) NULL, warning = function(w) NULL)
    if (!requireNamespace(pkg, quietly = TRUE)) {
      message("  Trying BiocManager...")
      tryCatch(
        BiocManager::install(pkg, ask = FALSE, update = FALSE),
        error   = function(e) message("  FAILED: ", e$message),
        warning = function(w) NULL
      )
    }
    if (requireNamespace(pkg, quietly = TRUE))
      message("  OK: ", pkg, " (", as.character(packageVersion(pkg)), ")")
    else
      message("  FAILED: ", pkg)
  } else {
    message("Already installed: ", pkg,
            " (", as.character(packageVersion(pkg)), ")")
  }
}

Verify the installation

After the script finishes, run this to check everything is ready:

R — verification 
pkgs <- c("Seurat", "SeuratObject", "ggplot2", "patchwork",
          "dplyr", "Matrix", "SingleR", "celldex",
          "harmony", "scales", "ggrepel", "BiocParallel",
          "scDblFinder", "SingleCellExperiment")

for (pkg in pkgs) {
  ok <- requireNamespace(pkg, quietly = TRUE)
  cat(sprintf("  %-22s %s\n", pkg, ifelse(ok, "OK", "MISSING")))
}

cat("\nSeurat version:", as.character(packageVersion("Seurat")), "\n")
# Must start with 5

Expected output:

PackageExpected status
SeuratOK (5.x.x)
SeuratObjectOK
ggplot2OK
patchworkOK
dplyrOK
MatrixOK
SingleROK
celldexOK
harmonyOK
scalesOK
ggrepelOK
BiocParallelOK
scDblFinderOK
SingleCellExperimentOK
If a package shows MISSING Try installing it individually via BiocManager, which works for both CRAN and Bioconductor packages:
R 
BiocManager::install("PACKAGE_NAME", force = TRUE)
# Then: Session > Restart R
If you see "namespace 'ggplot2' is imported by Seurat..." This is not an error. The package is already loaded by Seurat. It appears when library(ggplot2) is called a second time in the same session. Always do Session > Restart R at the start of the course.
Step 5 · Path B, local install

Download the dataset

Skip this entire section if you are using the virtual machine — the dataset is already saved at data/gse149689_subset_3k.rds there.

5
Download gse149689_subset_3k.rds
13.5 MB | CITE-seq dataset with RNA + ADT
▼

The dataset link is posted in Google Classroom under Data and Reference Materials. You can download it manually from the browser, or run the code below in R.

R — download 
# Create the data folder if it does not exist
dir.create("data", showWarnings = FALSE)

# The FILE_ID is posted in Google Classroom
FILE_ID <- "1mCg4VD91qK7pg-zL1iYUUBFWBr7fmmCM"

options(timeout = 600)
download.file(
  url      = paste0(
    "https://drive.google.com/uc?export=download&confirm=t&id=",
    FILE_ID
  ),
  destfile = "data/gse149689_subset_3k.rds",
  mode     = "wb"
)

Verify the download worked:

R — verify download 
sobj <- readRDS("data/gse149689_subset_3k.rds")
print(sobj)

# Expected output:
# An object of class Seurat
# 524 features across 3000 samples within 2 assays
# Active assay: RNA (500 features)
#  1 other assay present: ADT
What is in this dataset? A 3,000-cell CITE-seq experiment from Wilk et al., Nature Medicine 2021. Seven donors: 3 healthy and 4 COVID-19 (Mild, Moderate, Severe). Two measurement layers per cell: RNA (500 genes) and ADT (24 surface proteins).
The file is 13.5 MB. If the download is slow: Download it manually from the Google Drive link in Google Classroom and save it as data/gse149689_subset_3k.rds in your project folder.
Block 1 preview

What the course covers

This workshop focuses on troubleshooting real problems in single-cell CITE-seq analysis. You will run code that produces errors on purpose and learn to diagnose and fix them.

scRNA-seq
One RNA profile per cell. Around 90% zeros (dropout). Reveals cell type composition, transcriptional states, and population structure invisible to bulk sequencing.
CITE-seq adds
Surface protein measurements (ADT) sequenced alongside RNA. Bimodal signal, no dropout. Equivalent to flow cytometry data for each cell.
Why CITE-seq matters
CD4 RNA has heavy dropout in true CD4+ T cells. CD4 protein is clean. Without the protein layer, annotation of T cell subsets relies on an unreliable signal.
COVID-19 context
The dataset compares healthy donors with COVID-19 patients at three severity levels. Monocyte expansion and plasmablast enrichment are expected biological findings.

Schedule overview

BlockTopicTime
Block 0Setup (at home)Pre-course
Block 1Foundations: scRNA-seq, CITE-seq, dataset0:00 to 0:30
Block 2Object inspection and QC0:30 to 1:00
Block 3Preprocessing1:00 to 1:55
Break: 15 minutes
Block 4CITE-seq integrative analysis2:10 to 3:10
Block 5Troubleshooting scenarios (groups)3:10 to 4:10
Block 6Wrap-up and discussion4:10 to 4:50
What to expect Some code chunks produce errors intentionally. When you see an error on screen, stop and read the text below the chunk before running the next one. The errors are teaching moments, not mistakes.
Common issues

Troubleshooting before the course

!
Seurat v4 instead of v5 is installed
packageVersion("Seurat") returns 4.x.x
▼
R
install.packages("Seurat")
# Then Session > Restart R
packageVersion("Seurat")  # confirm it now starts with 5
!
celldex fails to install from CRAN
celldex is a Bioconductor package
▼
R
BiocManager::install("celldex", ask = FALSE)
# Then Session > Restart R
!
Seurat fails to install on Windows
Compilation error during install
▼

Install Rtools first from cran.r-project.org/bin/windows/Rtools. Choose the version that matches your R version. Then retry:

R
install.packages("Seurat")
!
Seurat fails on Mac Apple Silicon
Binary not found or architecture error
▼
R
install.packages("Seurat", type = "binary")

If that also fails, confirm you downloaded the ARM64 version of R from cran.r-project.org/bin/macosx.

!
Dataset download timeout
Connection too slow or Google Drive asks for login
▼

Download the file manually through your browser from the Google Classroom link. Save it as:

path
your_project_folder/data/gse149689_subset_3k.rds

If the Drive link asks for login, the instructor needs to change the sharing setting to "Anyone with the link".

Still stuck? Post a comment in Google Classroom with: your operating system, your R version (R.version$major), and the full error message. The instructor will help before the course day.
Single-Cell Survival Course  |  Seurat v5  |  GSE149689  |  Wilk et al., Nature Medicine 2021