Workshop Datasets

This page describes every dataset the workshop uses — what it is, how to load it, and where it lives on disk — grouped by core modules (the in-class three days) and bonus modules (self-paced). Most datasets load automatically from an R package; the few that don’t have a single download command.

Loading the core data — two options

The two core-module datasets — ifnb (Modules 01–08, 10) and airway (Module 06) — normally load straight from a Bioconductor package. If a package won’t install (the most common Day-1 snag is muscData / ExperimentHub), use the ready-made .rds instead: download one file and read it in with readRDS(). Both options give you the same object — pick whichever works on your machine.

Dataset Option A — from the package (default) Option B — from the .rds (fallback)
ifnb muscData::Kang18_8vs8(), then assemble the Seurat object (Tutorial 01, Step 1) readRDS("../data/ifnb_raw.rds")
airway library(airway); data(airway) readRDS("../data/airway_raw.rds")
TipQuick start with the .rds (no Bioconductor data packages needed)

  1. Download the file into your project’s data/ folder:

    • ifnb → ifnb_raw.rds — the assembled Seurat object before QC, i.e. Tutorial 01’s starting point
    • airway → airway_raw.rds — the bulk-RNA-seq RangedSummarizedExperiment used in Tutorial 06 Part A

  2. Read it in at the top of the tutorial, in place of the package load:

    ifnb   <- readRDS("../data/ifnb_raw.rds")   # Tutorial 01 — instead of the Kang18_8vs8() block
airway <- readRDS("../data/airway_raw.rds")     # Tutorial 06 — instead of library(airway); data(airway)

Prefer to pull the files from inside R rather than clicking the links? Download them straight into your project data/ folder:

dir.create("../data", showWarnings = FALSE)
base <- "https://wcresko.github.io/scRNAseq_tutorial/rds"
download.file(file.path(base, "ifnb_raw.rds"), "../data/ifnb_raw.rds", mode = "wb")
download.file(file.path(base, "airway_raw.rds"),   "../data/airway_raw.rds",   mode = "wb")

These .rds files are regenerated every time the site is rebuilt (render_all.sh runs tools/build_workshop_rds.R in the background), so they always match the package versions the tutorials use. The per-dataset sections below give the full Option A package commands and repeat the Option B .rds shortcut in context.

Splicing the .rds into the top of your Tutorial 01 script

Tutorial 01 builds ifnb from the package in its “Step 1 — Load the ifnb dataset” chunk (the block that starts with sce <- Kang18_8vs8() and ends by creating the ifnb object). To run from the .rds instead, leave the rest of the tutorial alone and make two small changes at the top:

1. (Optional) In the Setup chunk, comment out the two data-package libraries. They are only needed to build the object from scratch, so they aren’t required when you load the .rds:

# library(muscData)              # not needed when loading from the .rds
# library(SingleCellExperiment)  # not needed when loading from the .rds

2. Replace the entire Step 1 load chunk with this block. It downloads ifnb_raw.rds into your project data/ the first time, then reads it in. The result is the same ifnb object Step 1 would have built, so QC, normalization, HVGs — everything after it — runs unchanged:

# --- Load ifnb from the preassembled .rds (Option B) ----------------------
# Drop-in replacement for the Kang18_8vs8() block. Downloads once, then reuses
# the local copy. Run from your scripts/ folder so "../data" is the project data/.
dir.create("../data", showWarnings = FALSE)
ifnb_rds <- "../data/ifnb_raw.rds"
if (!file.exists(ifnb_rds)) {
  download.file("https://wcresko.github.io/scRNAseq_tutorial/rds/ifnb_raw.rds",
                ifnb_rds, mode = "wb")   # mode="wb" is required for binary .rds files
}
ifnb <- readRDS(ifnb_rds)
ifnb   # confirm: an ~24k-cell Seurat object with stim + seurat_annotations

If you already downloaded the file by clicking the link above, the download.file() step is skipped automatically and you just get the readRDS().

Note

Keep all your tutorial .qmd files in one scripts/ folder and run them from there, so ../data always points at the same project data/ folder (the same place Tutorial 01 writes ifnb_preprocessed.rds for Tutorial 02). Confirm with getwd() if a path doesn’t resolve.

Tutorial 06 (airway) works the same way. Its Part A loads the data with data(airway); replace that one line with the equivalent block:

# --- Load airway from the preassembled .rds (Option B) --------------------
dir.create("../data", showWarnings = FALSE)
airway_rds <- "../data/airway_raw.rds"
if (!file.exists(airway_rds)) {
  download.file("https://wcresko.github.io/scRNAseq_tutorial/rds/airway_raw.rds",
                airway_rds, mode = "wb")
}
airway <- readRDS(airway_rds)   # identical to library(airway); data(airway)

Expected directory layout

Make a project folder with a scripts/ subfolder, save the downloaded tutorial .qmd files into scripts/, and run them from there. On first run each tutorial auto-creates two sibling folders at the project root: data/ for the chained .rds objects passed from one tutorial to the next, and output/ModN/ for that module’s figures and tables. (See the downloadable README linked on the Materials page.)

my_scrnaseq_project/             # the project folder you create
├── scripts/                     # the downloaded .qmd files — run them from here
│   └── Tutorial_01 … Tutorial_17 (.qmd)
├── data/                        # auto-created on first run (sibling of scripts/)
│   ├── (ifnb → muscData cache; airway → R package — no files here)
│   └── ifnb_preprocessed.rds … ifnb_annotated_final.rds  # the chained hand-off objects (Tut 01→08)
└── output/                      # auto-created on first run (sibling of scripts/)
    └── Mod1/ … Mod17/           # each module's figures (.png) and tables (.csv)

In code the folders are written as ../data and ../output/ModN — the .. is “one level up from scripts/”, i.e. the project root. Tutorials 01–08 need nothing in data/ to start (ifnb is cached by Bioconductor’s muscData package on first use); they only write the chained .rds objects there. When you run a setup chunk it prints the absolute path it’s writing to, so you can always find your files. (The Talapas HPC track uses the same layout — the numbered scripts run from Exercise_Folder/scripts/ and read/write sibling ../data/ and ../output/ folders, just like the laptop tutorials.)

Core-module datasets

The three in-class days use just two datasets, and both load automatically from Bioconductor.

ifnb — Kang et al. 2017 (Modules 01–08, 10)

What it is. Peripheral blood mononuclear cells (PBMCs) from eight lupus donors. Each donor’s cells were split in half: one half was stimulated with interferon-β for 6 hours, the other held as an untreated control. Both were run on the 10x Chromium 3′ v1 assay.

  • CTRL — ~12,000 unstimulated PBMCs
  • STIM — ~12,000 IFN-β–stimulated PBMCs
  • Total — ~24,000 annotated singlets across two samples (the muscData build; the older SeuratData ifnb was ~14k)

This structure is what makes it the workshop’s backbone: it is small enough to run end-to-end on a laptop, yet it carries a real condition (CTRL vs STIM) and real biological replicates (8 donors). That combination is exactly what the integration (Module 05), pseudobulk DE (Module 06), and differential-abundance (Module 08) modules need — on a single-sample dataset those analyses have nothing to compare.

Cell metadata What it is
stim Condition — CTRL or STIM (the two samples integrated in Module 05).
ind (→ donor) Donor ID — one of 8 lupus patients; the replicate unit for DE / DA.
seurat_annotations Author-curated PBMC subtype (CD14/CD16 Mono, CD4/CD8 T, B, NK, DC, pDC, Mk…) — ground truth for the annotation modules.
nCount_RNA / nFeature_RNA Total UMIs / detected genes per cell.
percent.mt Mitochondrial-read fraction (added during QC).

Load it (one-time). No wget/curl — the data comes through the R package:

install.packages(c("Seurat", "tidyverse", "BiocManager"))
BiocManager::install("muscData")
invisible(muscData::Kang18_8vs8())   # first call downloads ~25 MB via ExperimentHub and caches it

The first Kang18_8vs8() call downloads ~25 MB into your local ExperimentHub cache; every subsequent call is instant. Tutorial 01 converts the returned SingleCellExperiment into the Seurat object used throughout Modules 01–08, and Module 10 loads the same data on Talapas (script 01_qc_preprocessing.R).

TipOption B — preassembled .rds (skip the muscData install)

If muscData / ExperimentHub won’t install, download ifnb_raw.rds into your project data/ and read it in instead of running Kang18_8vs8():

ifnb <- readRDS("../data/ifnb_raw.rds")

This is the same assembled Seurat object Tutorial 01 builds in Step 1 — CTRL + STIM, cleaned gene symbols, with the stim and seurat_annotations metadata — so you pick up right at the QC step. See Loading the core data — two options for the download link and an in-R download.file() snippet.

airway — Himes et al. 2014 (Module 06, DESeq2 primer)

What it is. A bulk RNA-seq dataset — the canonical teaching set for DESeq2. Four primary human airway smooth-muscle cell lines, each profiled untreated and after treatment with the steroid dexamethasone, giving 8 samples in a paired 4-donor × 2-condition design.

Why it’s here. Module 06 teaches pseudobulk differential expression, which is just bulk DESeq2 applied to per-cell-type aggregated counts. Learning the negative-binomial GLM, size factors, dispersion shrinkage, and contrasts on clean, well-behaved bulk data first — airway — makes the single-cell pseudobulk step that follows almost mechanical.

Sample metadata What it is
dex Treatment — untrt or trt (dexamethasone); the contrast of interest.
cell Cell-line donor (one of four); the blocking factor in the paired design.
SampleName / Run Sample and SRA run identifiers.

Load it. The package ships with the data — nothing to download:

BiocManager::install("airway")
library(airway); data(airway)
TipOption B — preassembled .rds

The airway package is small and usually installs cleanly, but if it won’t, download airway_raw.rds into your project data/ and read it in instead of library(airway); data(airway):

airway <- readRDS("../data/airway_raw.rds")   # identical RangedSummarizedExperiment

(DESeq2, loaded in Tutorial 06, brings in SummarizedExperiment, so assay(airway) and colData(airway) work exactly as in Option A.)

Core-path disk budget

Item Size
ifnb raw counts (compressed cache) ~25 MB
airway (Bioconductor package) ~3 MB
Per-tutorial .rds snapshots (ifnb_preprocessed.rds, ifnb_clustered.rds, …) ~300–500 MB each

Plan for ~2 GB total for Modules 01–08 including chained .rds snapshots — much less if you delete intermediates as you go.

Bonus-module datasets

The self-paced bonus modules each bring their own dataset. The R-package ones (stxBrain, reference atlases) load automatically; the rest have a single download command.

Modules 11–12 — raw 10x FASTQs for Cell Ranger

The upstream bonus modules run cellranger count (RNA, Module 11) and cellranger-atac count (ATAC, Module 12) to turn raw 10x FASTQs into the count matrices the core pipeline consumes. For practice, 10x publishes small public PBMC 1k test sets that finish in well under an hour on a compute node:

mkdir -p ../data && cd ../data

# Module 11 — PBMC 1k v3 RNA FASTQs (~5 GB)
wget https://s3-us-west-2.amazonaws.com/10x.files/samples/cell-exp/3.0.0/pbmc_1k_v3/pbmc_1k_v3_fastqs.tar

# Module 12 — PBMC 1k v1 ATAC FASTQs (~3 GB)
wget https://s3-us-west-2.amazonaws.com/10x.files/samples/cell-atac/1.2.0/atac_pbmc_1k_v1/atac_pbmc_1k_v1_fastqs.tar

Cell Ranger also needs a reference genome bundle (the heavyweight component, ~12 GB each). On Talapas these belong in shared project storage (/projects/<PIRG>/refs/), not your home directory:

# RNA gene-expression reference (Module 11)
wget https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2024-A.tar.gz

# ATAC / multiome reference (Module 12)
wget https://cf.10xgenomics.com/supp/cell-atac/refdata-cellranger-arc-GRCh38-2024-A.tar.gz

The full step-by-step (installing Cell Ranger, the SLURM batch script, scaling to many samples with an array job) is in Tutorial 11 and Tutorial 12. To run the whole pipeline from raw reads on a larger, multi-donor sample, see the optional Full Talapas run from raw FASTQs roadmap.

Module 13 — GSE152418 (COVID-19 PBMC bulk RNA-seq, WGCNA)

What it is. PBMC bulk RNA-seq from a cross-sectional COVID-19 study (Arunachalam et al. 2020, Science), ~34 samples spanning a severity gradient from healthy controls through convalescent, moderate, severe, and ICU patients. The severity axis is the sample-level trait WGCNA correlates its co-expression modules against.

Download it. One supplementary file from GEO, unzipped in place:

# Run this from your project's scripts/ folder; it puts the file in the project data/
mkdir -p ../data && cd ../data
wget https://ftp.ncbi.nlm.nih.gov/geo/series/GSE152nnn/GSE152418/suppl/GSE152418_p20047_Study1_RawCounts.txt.gz
gunzip GSE152418_p20047_Study1_RawCounts.txt.gz

The per-sample metadata is fetched inside R with GEOquery::getGEO() during the tutorial — no separate download.

Module 15 — PBMC 10k scATAC-seq v1 (10x, hg19)

What it is. Single-cell ATAC-seq of ~10,000 PBMCs from a healthy donor — the v1 / hg19 release. Each cell is summarized as fragment counts over accessible peaks; the fragments file is the canonical scATAC representation. Same dataset as the Signac PBMC vignette.

Download it. Four files load directly into Signac (there is no R-package source for them):

# Run this from your project's scripts/ folder; it puts the files in the project data/
mkdir -p ../data && cd ../data
wget https://cf.10xgenomics.com/samples/cell-atac/1.0.1/atac_v1_pbmc_10k/atac_v1_pbmc_10k_filtered_peak_bc_matrix.h5
wget https://cf.10xgenomics.com/samples/cell-atac/1.0.1/atac_v1_pbmc_10k/atac_v1_pbmc_10k_singlecell.csv
wget https://cf.10xgenomics.com/samples/cell-atac/1.0.1/atac_v1_pbmc_10k/atac_v1_pbmc_10k_fragments.tsv.gz
wget https://cf.10xgenomics.com/samples/cell-atac/1.0.1/atac_v1_pbmc_10k/atac_v1_pbmc_10k_fragments.tsv.gz.tbi
Warning

Use the v1 / hg19 files above. The later Next GEM v1.1 re-release of the same sample is mapped to hg38 (filenames prefixed atac_v1_pbmc_10k_nextgem_*); the tutorial pairs with EnsDb.Hsapiens.v75, which is hg19, so mixing releases produces coordinate errors. The fragments.tsv.gz and its .tbi index must always stay together.

Module 16 — stxBrain (10x Visium adult mouse brain)

What it is. A spatial dataset: two 10x Visium sections from the same adult mouse brain — one anterior (~2,700 spots) and one posterior (~3,300 spots), ~6,000 spots total, ~50 MB. Each spot is a ~55 µm patch capturing ~1–10 cells, and every spot keeps its x/y position on the slide plus the underlying H&E image. The anterior/posterior pair mirrors the two-sample structure of ifnb, so the Visium integration workflow parallels Module 05.

Variable / slot What it is
nCount_Spatial / nFeature_Spatial Total UMIs / detected genes under the spot.
orig.ident / section Anterior vs posterior section.
images slot H&E image plus each spot’s pixel/tissue coordinates, used for spatial plots.

Load it. Through SeuratData — no manual download, no 10x click-through:

SeuratData::InstallData("stxBrain")
ant  <- LoadData("stxBrain", type = "anterior1")
post <- LoadData("stxBrain", type = "posterior1")

Reference / annotation datasets (Modules 04, 15)

These are pulled automatically by their R packages on first use (internet required once), not downloaded by hand:

Reference Loaded by Used in
Azimuth pbmcref Azimuth / SeuratData Module 04 (reference annotation)
EnsDb.Hsapiens.v75 Bioconductor Module 15 (scATAC, hg19 annotation)

Full-workshop disk budget

Path Compressed Extracted
Core path (ifnb + airway + .rds snapshots) ~30 MB up to ~2 GB
Module 13 — GSE152418 raw counts ~7 MB ~80 MB
Module 15 — PBMC 10k scATAC ~2.5 GB ~5 GB
Modules 11–12 — PBMC 1k FASTQs (RNA + ATAC) ~8 GB ~8 GB
Cell Ranger reference bundles (Modules 11–12) — ~30 GB (shared project storage)
Reference / annotation caches (Modules 04, 15) — ~500 MB

For a laptop-only run of Modules 01–08, plan for ~3 GB including caches and intermediates. The bonus modules add storage as you opt into them; the Cell Ranger references in particular are large and belong in shared cluster storage, not $HOME.

Back to top