From 165fb7b47160f91cbada26bdfc97217a41069e06 Mon Sep 17 00:00:00 2001 From: Nuoya Wang Date: Tue, 3 Nov 2026 14:58:04 -0500 Subject: [PATCH] Pkgdown revision pkgdown revision to eliminate dependence on SeuratData --- .github/workflows/pkgdown.yaml | 39 +++-- .gitignore | 3 + CLAUDE.md | 3 +- DESCRIPTION | 1 + NAMESPACE | 1 + NEWS.md | 3 + R/download_NICHESv2_data.R | 167 +++++++++++++++++++ _pkgdown.yml | 4 + data-raw/build_tutorial_data.R | 130 +++++++++++++++ man/download_NICHESv2_data.Rd | 67 ++++++++ tests/testthat/test-download_NICHESv2_data.R | 101 +++++++++++ vignettes/articles/for-reviewers.Rmd | 22 ++- vignettes/articles/nonspatial-tutorial.Rmd | 42 ++--- vignettes/articles/seurat-objects.Rmd | 115 +++++++++++++ vignettes/articles/spatial-tutorial.Rmd | 51 ++---- working-scripts-NW/v1_facts_sheet.md | 24 ++- 16 files changed, 675 insertions(+), 98 deletions(-) create mode 100644 R/download_NICHESv2_data.R create mode 100644 data-raw/build_tutorial_data.R create mode 100644 man/download_NICHESv2_data.Rd create mode 100644 tests/testthat/test-download_NICHESv2_data.R create mode 100644 vignettes/articles/seurat-objects.Rmd diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 64092be..f5f2d9e 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -1,8 +1,11 @@ # .github/workflows/pkgdown.yaml # # Builds the website and publishes it to the gh-pages branch on every push to -# main. The tutorials really run here, so each build installs SeuratData and -# downloads both public test datasets. A failed build publishes nothing, and the +# main. The tutorials really run here. They download their data with +# download_NICHESv2_data() from this repository's data-v1 release, so they need +# nothing outside NICHESv2. Only the "Starting from a Seurat object" page uses +# SeuratData; its install step may fail without stopping the build, and the page +# then shows its code without output. A failed build publishes nothing, and the # live site stays as it was. # # To test a build without publishing it, start this workflow by hand from the @@ -36,24 +39,32 @@ jobs: with: use-public-rspm: true - # Step 3: install this package, everything in DESCRIPTION, and the tools - # the website needs + # Step 3: install this package, everything in DESCRIPTION, and pkgdown - uses: r-lib/actions/setup-r-dependencies@v2 with: extra-packages: | any::pkgdown - any::remotes - any::Seurat local::. - # Step 4: install SeuratData and download the test datasets - # SeuratData isn't on CRAN, so it comes from GitHub. It gets its own step - # because Step 3 would also require Azimuth, an optional SeuratData - # package that isn't on CRAN or Bioconductor. - - name: Install SeuratData and test datasets - run: | - remotes::install_github("satijalab/seurat-data", upgrade = "never") - SeuratData::InstallData(c("stxBrain", "ifnb")) + # Step 4 (optional): install Seurat and SeuratData for the Seurat page + # continue-on-error: true → a failure here doesn't stop the build + # dependencies: "hard" → skips SeuratData's optional Azimuth + # package, which isn't on CRAN + - name: Install Seurat and SeuratData (optional) + id: seuratdata + continue-on-error: true + uses: r-lib/actions/setup-r-dependencies@v2 + with: + packages: | + any::Seurat + github::satijalab/seurat-data + dependencies: '"hard"' + cache: false + + - name: Download the SeuratData datasets (optional) + if: steps.seuratdata.outcome == 'success' + continue-on-error: true + run: SeuratData::InstallData(c("stxBrain", "ifnb")) shell: Rscript {0} # Step 5: build the site diff --git a/.gitignore b/.gitignore index 1fc4c48..034605f 100644 --- a/.gitignore +++ b/.gitignore @@ -55,3 +55,6 @@ docs # Local Claude Code settings and OmniPath download logs .claude/settings.local.json omnipathr-log/ + +# Tutorial data built by data-raw/build_tutorial_data.R; uploaded to a GitHub release +data-raw/tutorial-data/ diff --git a/CLAUDE.md b/CLAUDE.md index 67190b1..caaf750 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,6 +110,7 @@ Custom data frames are also accepted; must have `ligand` and `receptor` columns - `extract_NICHESInputs_Seurat()` — supports Seurat V4 and V5; detects assay class automatically; **spatial coordinates must be extracted manually** and added to the returned metadata before calling `create_NICHESObject()` - `extract_NICHESInputs_AnnData()` — reads `.h5ad` via `rhdf5` only; no Python required +- `download_NICHESv2_data()` — downloads the two public tutorial datasets (`"stxBrain"`, `"ifnb"`) from the GitHub release `data-v1`, checks their MD5 sums and caches them in `tools::R_user_dir("NICHESv2", "cache")`. On a failed download or a wrong sum it returns `NULL` with a message instead of an error, as CRAN asks of internet resources. `data-raw/build_tutorial_data.R` builds the release files; rebuilding them changes the MD5 sums in `.niches_datasets()`. The `NICHESv2.data.url` option points the function at another folder, for tests and local site builds. ## Repository layout notes @@ -119,7 +120,7 @@ Custom data frames are also accepted; must have `ligand` and `receptor` columns - `data-raw/` — scripts that build the bundled data files; excluded from package build - `tests/testthat/` — one test file per source file; `helper-testutils.R` provides shared fixtures - `vignettes/` — one vignette, `NICHESv2.Rmd`, which runs on bundled data; `vignettes/articles/` holds the website pages and is excluded from the package build -- `.github/workflows/` — `R-CMD-check.yaml` runs the checks; `pkgdown.yaml` builds the website and publishes it from `main`, removing this file first because pkgdown turns top-level Markdown files into pages +- `.github/workflows/` — `R-CMD-check.yaml` runs the checks; `pkgdown.yaml` builds the website and publishes it from `main`, removing this file first because pkgdown turns top-level Markdown files into pages. Only the Seurat page uses SeuratData; its install steps may fail without stopping the build - `demo-scripts/` — standalone R scripts demonstrating real-dataset usage (not part of the package build) - `working-scripts-MSBR/` and `working-scripts-NW/` — exploratory and prototyping scripts; not part of the package - `package management/` — design documents diff --git a/DESCRIPTION b/DESCRIPTION index f11da91..c3f328a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -33,6 +33,7 @@ Imports: ggplot2 (>= 3.4.0), parallel, stats, + tools, utils Suggests: SeuratObject, diff --git a/NAMESPACE b/NAMESPACE index 3d49af0..8145977 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -18,6 +18,7 @@ export(compute_CellToCell) export(create_Edgelist_SamplingByType) export(create_Edgelist_Spatial) export(create_NICHESObject) +export(download_NICHESv2_data) export(export_to_TissuePlex) export(extract_NICHESInputs_AnnData) export(extract_NICHESInputs_Seurat) diff --git a/NEWS.md b/NEWS.md index 76763f8..b24ef18 100644 --- a/NEWS.md +++ b/NEWS.md @@ -19,6 +19,9 @@ First public release. Python. - `export_to_TissuePlex()` writes edges to a Parquet file for interactive viewing. +- `download_NICHESv2_data()` downloads the two public datasets used in the + website tutorials: a 10x Visium mouse brain section and interferon-beta + stimulated PBMCs. ## Changes for users of the 0.0.9000 development version diff --git a/R/download_NICHESv2_data.R b/R/download_NICHESv2_data.R new file mode 100644 index 0000000..c9750c0 --- /dev/null +++ b/R/download_NICHESv2_data.R @@ -0,0 +1,167 @@ +# download_NICHESv2_data.R ------------------------------------------------ +# Download one of the public datasets used by the website tutorials from a +# release of the NICHESv2 GitHub repository, check it, cache it, and return +# inputs ready for create_NICHESObject(). The files are built by +# data-raw/build_tutorial_data.R. +# +# FUNCTIONS: +# download_NICHESv2_data() -- main function +# .read_inputs() -- read inputs.rds with Matrix loaded +# .niches_data_url() -- release folder the files are attached to +# .niches_datasets() -- file name, MD5 sum and size of each dataset +# +# DEPS: tools, utils + + +# ============================================================================== +#' Download a Public Tutorial Dataset +#' +#' @description +#' Downloads one of the two public datasets used in the website tutorials, +#' checks its MD5 sum, and returns a count matrix and metadata ready for +#' \code{create_NICHESObject()}. The files are attached to a release of the +#' NICHESv2 GitHub repository, so no other package is needed. Each dataset is +#' downloaded once and then read from \code{cache.dir}. +#' +#' @section Datasets: +#' \describe{ +#' \item{\code{"stxBrain"}}{10x Genomics Visium mouse brain, sagittal-anterior +#' section 1: 2,696 spots and 31,053 genes, with spot coordinates in +#' \code{x} and \code{y}. About 14 MB. CC BY 4.0, credit 10x Genomics.} +#' \item{\code{"ifnb"}}{Human PBMCs, untreated or stimulated with +#' interferon-beta (Kang et al., 2018): 13,999 cells and 14,053 genes, with +#' the condition in \code{stim} and cell-type labels from the Satija Lab in +#' \code{seurat_annotations}. About 11 MB. CC BY 4.0.} +#' } +#' Each dataset's folder in \code{cache.dir} also holds a \code{PROVENANCE.md} +#' file stating its source, license and the changes made. +#' +#' @param dataset \code{"stxBrain"} or \code{"ifnb"}. +#' @param cache.dir Folder to keep downloaded files in. Default: the NICHESv2 +#' user cache folder, \code{tools::R_user_dir("NICHESv2", "cache")}. Delete +#' the folder to free the space. +#' @param force Download again even if the dataset is already cached. +#' Default \code{FALSE}. +#' @param verbose Print progress messages. Default \code{TRUE}. +#' +#' @return A list with \code{count.mtx} (a sparse genes x cells matrix of raw +#' counts) and \code{meta.data} (a data frame with one row per cell), the +#' same shape that \code{extract_NICHESInputs_Seurat()} returns. If the +#' download fails, or the file doesn't match its MD5 sum, a message explains +#' why and \code{NULL} is returned invisibly. +#' +#' @references +#' Kang HM, Subramaniam M, Targ S, et al. (2018). Multiplexed droplet +#' single-cell RNA-sequencing using natural genetic variation. +#' \emph{Nature Biotechnology}, 36(1), 89--94. \doi{10.1038/nbt.4042} +#' +#' @examples +#' \donttest{ +#' # Downloads about 11 MB, kept in a temporary folder here. +#' inputs <- download_NICHESv2_data("ifnb", cache.dir = tempdir()) +#' if (!is.null(inputs)) dim(inputs$count.mtx) +#' } +#' +#' @export +download_NICHESv2_data <- function(dataset, + cache.dir = tools::R_user_dir("NICHESv2", "cache"), + force = FALSE, + verbose = TRUE) { + + datasets <- .niches_datasets() + if (missing(dataset) || !is.character(dataset) || length(dataset) != 1L || + !dataset %in% names(datasets)) + stop( + "[download_NICHESv2_data] 'dataset' must be one of: ", + paste0("'", names(datasets), "'", collapse = ", "), ".", + call. = FALSE + ) + + info <- datasets[[dataset]] + rds.file <- file.path(cache.dir, dataset, "inputs.rds") + + if (!force && file.exists(rds.file)) { + if (verbose) + message("[download_NICHESv2_data] Reading cached '", dataset, "' from ", + dirname(rds.file)) + return(.read_inputs(rds.file)) + } + + # -- Download and check the zip --------------------------------------------- + dir.create(cache.dir, recursive = TRUE, showWarnings = FALSE) + zip.file <- file.path(cache.dir, info$file) + url <- paste(.niches_data_url(), info$file, sep = "/") + + if (verbose) + message("[download_NICHESv2_data] Downloading '", dataset, "' (", + info$size, ") ...") + old.options <- options(timeout = max(600, getOption("timeout"))) + on.exit(options(old.options), add = TRUE) + + downloaded <- tryCatch( + utils::download.file(url, zip.file, mode = "wb", quiet = TRUE) == 0L, + error = function(e) FALSE, + warning = function(w) FALSE + ) + if (!downloaded || !file.exists(zip.file)) { + unlink(zip.file) + message( + "[download_NICHESv2_data] Could not download '", dataset, "' from\n ", + url, "\n Check your internet connection and try again." + ) + return(invisible(NULL)) + } + + if (!identical(unname(tools::md5sum(zip.file)), info$md5)) { + unlink(zip.file) + message( + "[download_NICHESv2_data] The downloaded file for '", dataset, + "' doesn't match its expected MD5 sum, so it was deleted.\n ", + "Try again with force = TRUE. If this keeps happening, please open an ", + "issue at https://github.com/RaredonLab/NICHESv2/issues" + ) + return(invisible(NULL)) + } + + # -- Unpack into cache.dir// --------------------------------------- + unlink(file.path(cache.dir, dataset), recursive = TRUE) + utils::unzip(zip.file, exdir = cache.dir) + unlink(zip.file) + + .read_inputs(rds.file) +} + + +## INTERNAL HELPERS ---- + +#' Read an inputs.rds file. Matrix is loaded first: otherwise readRDS() loads it +#' while unserializing, and the first dim() call on the matrix returns NULL. +#' @noRd +.read_inputs <- function(rds.file) { + loadNamespace("Matrix") + readRDS(rds.file) +} + +#' Release folder that holds the dataset files. The NICHESv2.data.url option +#' points elsewhere for tests and for building the site before an upload. +#' @noRd +.niches_data_url <- function() { + getOption( + "NICHESv2.data.url", + "https://github.com/RaredonLab/NICHESv2/releases/download/data-v1" + ) +} + +#' File name, MD5 sum and download size of each dataset. The sums come from +#' data-raw/build_tutorial_data.R and must match the uploaded files. +#' @noRd +.niches_datasets <- function() { + list( + stxBrain = list(file = "stxBrain.zip", + md5 = "f2085cbb105198f29e94456eeebdf261", + size = "14 MB"), + ifnb = list(file = "ifnb.zip", + md5 = "bd4d47cac9dc110aa253f4c6e95fcc43", + size = "11 MB") + ) +} diff --git a/_pkgdown.yml b/_pkgdown.yml index 0dad402..e12ac25 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -18,6 +18,8 @@ navbar: href: articles/spatial-tutorial.html - text: "Non-spatial: stimulated PBMCs" href: articles/nonspatial-tutorial.html + - text: Starting from a Seurat object + href: articles/seurat-objects.html guides: text: Guides menu: @@ -40,6 +42,7 @@ articles: contents: - articles/spatial-tutorial - articles/nonspatial-tutorial + - articles/seurat-objects - title: Guides navbar: ~ contents: @@ -86,6 +89,7 @@ reference: - create_Edgelist_SamplingByType - title: Example data contents: + - download_NICHESv2_data - NICHESv2_inputs - NICHESv2_example - title: LR databases diff --git a/data-raw/build_tutorial_data.R b/data-raw/build_tutorial_data.R new file mode 100644 index 0000000..102739c --- /dev/null +++ b/data-raw/build_tutorial_data.R @@ -0,0 +1,130 @@ +# build_tutorial_data.R +# +# PURPOSE: Builds the two public datasets the website tutorials download with +# download_NICHESv2_data(). Each dataset becomes one zip file holding +# inputs.rds (a sparse count matrix and its metadata, ready for +# create_NICHESObject()) and PROVENANCE.md (source, license, changes). +# The zips and a SHA256SUMS file are uploaded by hand as assets of the +# GitHub release named in .niches_data_url(). Both datasets are +# CC BY 4.0, so this copy credits the sources and states the changes. +# +# NEEDS: SeuratObject, SeuratData, and its datasets installed once with +# SeuratData::InstallData(c("stxBrain", "ifnb")). +# +# USAGE: Run from the package root: +# Rscript data-raw/build_tutorial_data.R +# Then copy the printed MD5 sums into .niches_datasets() in +# R/download_NICHESv2_data.R. Output goes to data-raw/tutorial-data/, +# which git ignores. + +suppressPackageStartupMessages({ + library(SeuratObject) + library(SeuratData) +}) +devtools::load_all(quiet = TRUE) + +out.dir <- "data-raw/tutorial-data" +unlink(out.dir, recursive = TRUE) +dir.create(out.dir, recursive = TRUE) + +.write_dataset <- function(name, inputs, provenance) { + folder <- file.path(out.dir, name) + dir.create(folder) + saveRDS(inputs, file.path(folder, "inputs.rds"), compress = "xz") + writeLines(provenance, file.path(folder, "PROVENANCE.md")) + zip.file <- paste0(name, ".zip") + old.wd <- setwd(out.dir) + on.exit(setwd(old.wd)) + utils::zip(zip.file, files = name, flags = "-r9Xq") + unlink(name, recursive = TRUE) + invisible(file.path(out.dir, zip.file)) +} + + +## stxBrain: 10x Visium mouse brain, anterior section 1 ---- + +data("anterior1") +spatial <- extract_NICHESInputs_Seurat( + seurat.obj = anterior1, + assay = "Spatial", + layer = "counts", + verbose = FALSE +) +coords <- GetTissueCoordinates(anterior1) +spatial$meta.data$x <- coords[rownames(spatial$meta.data), "x"] +spatial$meta.data$y <- coords[rownames(spatial$meta.data), "y"] + +.write_dataset("stxBrain", spatial, c( + "# stxBrain: 10x Visium mouse brain, sagittal-anterior section 1", + "", + "## Source", + "", + "10x Genomics, \"Mouse Brain Serial Section 1 (Sagittal-Anterior)\", Space", + "Ranger 1.0.0. Taken from the `anterior1` object in the SeuratData package", + sprintf("`stxBrain.SeuratData` %s (Satija Lab).", + utils::packageVersion("stxBrain.SeuratData")), + "", + "## License", + "", + "CC BY 4.0, https://creativecommons.org/licenses/by/4.0/", + "Credit: 10x Genomics.", + "", + "## Changes", + "", + "- Kept the raw counts of the `Spatial` assay (genes x spots) and the spot", + " metadata.", + "- Added spot coordinates `x` and `y` from `GetTissueCoordinates()`.", + "- Saved them as a list with `count.mtx` (sparse matrix) and `meta.data`", + " (data frame) for NICHESv2. No values were changed." +)) + + +## ifnb: interferon-beta stimulated and control PBMCs ---- + +data("ifnb") +nonspatial <- extract_NICHESInputs_Seurat( + seurat.obj = ifnb, + assay = "RNA", + layer = "counts", + verbose = FALSE +) + +.write_dataset("ifnb", nonspatial, c( + "# ifnb: interferon-beta stimulated and control human PBMCs", + "", + "## Source", + "", + "Kang HM, Subramaniam M, Targ S, et al. Multiplexed droplet single-cell", + "RNA-sequencing using natural genetic variation. Nat Biotechnol.", + "2018;36(1):89-94. doi:10.1038/nbt.4042. GEO: GSE96583.", + "Taken from the `ifnb` object in the SeuratData package", + sprintf("`ifnb.SeuratData` %s (Satija Lab), which adds the cell-type labels", + utils::packageVersion("ifnb.SeuratData")), + "in `seurat_annotations`.", + "", + "## License", + "", + "CC BY 4.0, https://creativecommons.org/licenses/by/4.0/, as stated by", + "`ifnb.SeuratData`. Credit: Kang et al. (2018) and the Satija Lab.", + "", + "## Changes", + "", + "- Kept the raw counts of the `RNA` assay (genes x cells) and the cell", + " metadata, including `stim` and `seurat_annotations`.", + "- Saved them as a list with `count.mtx` (sparse matrix) and `meta.data`", + " (data frame) for NICHESv2. No values were changed." +)) + + +## Checksums ---- + +zips <- file.path(out.dir, c("stxBrain.zip", "ifnb.zip")) +sha <- vapply(zips, function(f) { + strsplit(system2("shasum", c("-a", "256", shQuote(f)), stdout = TRUE), " ")[[1L]][1L] +}, character(1L)) +writeLines(paste0(sha, " ", basename(zips)), file.path(out.dir, "SHA256SUMS")) + +for (f in zips) { + cat(sprintf("%-12s %6.1f MB md5 %s\n", basename(f), file.size(f) / 1e6, + unname(tools::md5sum(f)))) +} diff --git a/man/download_NICHESv2_data.Rd b/man/download_NICHESv2_data.Rd new file mode 100644 index 0000000..41c8f71 --- /dev/null +++ b/man/download_NICHESv2_data.Rd @@ -0,0 +1,67 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/download_NICHESv2_data.R +\name{download_NICHESv2_data} +\alias{download_NICHESv2_data} +\title{Download a Public Tutorial Dataset} +\usage{ +download_NICHESv2_data( + dataset, + cache.dir = tools::R_user_dir("NICHESv2", "cache"), + force = FALSE, + verbose = TRUE +) +} +\arguments{ +\item{dataset}{\code{"stxBrain"} or \code{"ifnb"}.} + +\item{cache.dir}{Folder to keep downloaded files in. Default: the NICHESv2 +user cache folder, \code{tools::R_user_dir("NICHESv2", "cache")}. Delete +the folder to free the space.} + +\item{force}{Download again even if the dataset is already cached. +Default \code{FALSE}.} + +\item{verbose}{Print progress messages. Default \code{TRUE}.} +} +\value{ +A list with \code{count.mtx} (a sparse genes x cells matrix of raw + counts) and \code{meta.data} (a data frame with one row per cell), the + same shape that \code{extract_NICHESInputs_Seurat()} returns. If the + download fails, or the file doesn't match its MD5 sum, a message explains + why and \code{NULL} is returned invisibly. +} +\description{ +Downloads one of the two public datasets used in the website tutorials, +checks its MD5 sum, and returns a count matrix and metadata ready for +\code{create_NICHESObject()}. The files are attached to a release of the +NICHESv2 GitHub repository, so no other package is needed. Each dataset is +downloaded once and then read from \code{cache.dir}. +} +\section{Datasets}{ + +\describe{ + \item{\code{"stxBrain"}}{10x Genomics Visium mouse brain, sagittal-anterior + section 1: 2,696 spots and 31,053 genes, with spot coordinates in + \code{x} and \code{y}. About 14 MB. CC BY 4.0, credit 10x Genomics.} + \item{\code{"ifnb"}}{Human PBMCs, untreated or stimulated with + interferon-beta (Kang et al., 2018): 13,999 cells and 14,053 genes, with + the condition in \code{stim} and cell-type labels from the Satija Lab in + \code{seurat_annotations}. About 11 MB. CC BY 4.0.} +} +Each dataset's folder in \code{cache.dir} also holds a \code{PROVENANCE.md} +file stating its source, license and the changes made. +} + +\examples{ +\donttest{ +# Downloads about 11 MB, kept in a temporary folder here. +inputs <- download_NICHESv2_data("ifnb", cache.dir = tempdir()) +if (!is.null(inputs)) dim(inputs$count.mtx) +} + +} +\references{ +Kang HM, Subramaniam M, Targ S, et al. (2018). Multiplexed droplet +single-cell RNA-sequencing using natural genetic variation. +\emph{Nature Biotechnology}, 36(1), 89--94. \doi{10.1038/nbt.4042} +} diff --git a/tests/testthat/test-download_NICHESv2_data.R b/tests/testthat/test-download_NICHESv2_data.R new file mode 100644 index 0000000..49358c2 --- /dev/null +++ b/tests/testthat/test-download_NICHESv2_data.R @@ -0,0 +1,101 @@ +# ============================================================================== +# FILE: tests/testthat/test-download_NICHESv2_data.R +# PURPOSE: Unit tests for download_NICHESv2_data(). +# No internet needed: a small zip built from NICHESv2_inputs is served +# from a local folder through a file:// URL. +# ============================================================================== + +# Builds /tiny.zip holding tiny/inputs.rds and returns the dataset +# entry and the file:// URL of src.dir. +.make_test_release <- function(src.dir) { + data("NICHESv2_inputs", package = "NICHESv2", envir = environment()) + inputs <- NICHESv2_inputs[c("count.mtx", "meta.data")] + dir.create(file.path(src.dir, "tiny"), recursive = TRUE) + saveRDS(inputs, file.path(src.dir, "tiny", "inputs.rds")) + writeLines("# tiny", file.path(src.dir, "tiny", "PROVENANCE.md")) + old.wd <- setwd(src.dir) + on.exit(setwd(old.wd)) + utils::zip("tiny.zip", files = "tiny", flags = "-r9Xq") + unlink(file.path(src.dir, "tiny"), recursive = TRUE) + path <- normalizePath(src.dir, winslash = "/") + list( + inputs = inputs, + entry = list(file = "tiny.zip", + md5 = unname(tools::md5sum(file.path(src.dir, "tiny.zip"))), + size = "1 KB"), + url = paste0("file://", if (startsWith(path, "/")) "" else "/", path) + ) +} + +# ── Argument checks ──────────────────────────────────────────────────────────── + +test_that("download_NICHESv2_data: unknown or missing dataset stops", { + expect_error(download_NICHESv2_data("pbmc3k", cache.dir = tempfile()), + "must be one of") + expect_error(download_NICHESv2_data(cache.dir = tempfile()), "must be one of") + expect_error(download_NICHESv2_data(c("stxBrain", "ifnb"), + cache.dir = tempfile()), + "must be one of") +}) + +test_that("download_NICHESv2_data: both datasets are registered", { + datasets <- NICHESv2:::.niches_datasets() + expect_setequal(names(datasets), c("stxBrain", "ifnb")) + for (d in datasets) expect_match(d$md5, "^[0-9a-f]{32}$") +}) + +# ── Download, cache and failure paths ────────────────────────────────────────── + +test_that("download_NICHESv2_data: downloads, unpacks and then reads the cache", { + skip_if(Sys.which("zip") == "", "zip program not available") + src.dir <- withr::local_tempdir() + cache.dir <- withr::local_tempdir() + release <- .make_test_release(src.dir) + withr::local_options(NICHESv2.data.url = release$url) + local_mocked_bindings(.niches_datasets = function() list(tiny = release$entry)) + + result <- download_NICHESv2_data("tiny", cache.dir = cache.dir, verbose = FALSE) + expect_equal(result, release$inputs) + expect_true(file.exists(file.path(cache.dir, "tiny", "PROVENANCE.md"))) + expect_false(file.exists(file.path(cache.dir, "tiny.zip"))) + + # The second call reads the cache, even with the source gone. + unlink(file.path(src.dir, "tiny.zip")) + expect_message( + cached <- download_NICHESv2_data("tiny", cache.dir = cache.dir), + "Reading cached" + ) + expect_equal(cached, release$inputs) +}) + +test_that("download_NICHESv2_data: a wrong MD5 sum returns NULL with a message", { + skip_if(Sys.which("zip") == "", "zip program not available") + src.dir <- withr::local_tempdir() + cache.dir <- withr::local_tempdir() + release <- .make_test_release(src.dir) + release$entry$md5 <- strrep("0", 32L) + withr::local_options(NICHESv2.data.url = release$url) + local_mocked_bindings(.niches_datasets = function() list(tiny = release$entry)) + + expect_message( + result <- download_NICHESv2_data("tiny", cache.dir = cache.dir, verbose = FALSE), + "doesn't match its expected MD5 sum" + ) + expect_null(result) + expect_length(list.files(cache.dir), 0L) +}) + +test_that("download_NICHESv2_data: a failed download returns NULL with a message", { + cache.dir <- withr::local_tempdir() + missing.dir <- normalizePath(withr::local_tempdir(), winslash = "/") + withr::local_options(NICHESv2.data.url = paste0( + "file://", if (startsWith(missing.dir, "/")) "" else "/", missing.dir, "/none" + )) + + expect_message( + result <- download_NICHESv2_data("ifnb", cache.dir = cache.dir, verbose = FALSE), + "Could not download 'ifnb'" + ) + expect_null(result) + expect_length(list.files(cache.dir), 0L) +}) diff --git a/vignettes/articles/for-reviewers.Rmd b/vignettes/articles/for-reviewers.Rmd index ea1c8a4..a1e6847 100644 --- a/vignettes/articles/for-reviewers.Rmd +++ b/vignettes/articles/for-reviewers.Rmd @@ -16,7 +16,7 @@ paper's figures, which used a separate dataset. ## 1. Install ```r -install.packages(c("remotes", "SeuratObject", "arrow")) +install.packages(c("remotes", "arrow")) remotes::install_github("RaredonLab/NICHESv2", ref = "main") ``` @@ -42,15 +42,15 @@ You should see 80 cells, 50 genes, 354 edges and 15 LRMs. ## 3. Get the test data -Both datasets come from -[SeuratData](https://github.com/satijalab/seurat-data). They download once, and -together take about 560 MB. SeuratData also installs the Seurat package, so this -step can take a while. NICHESv2 itself doesn't need Seurat. +Both datasets are attached to a +[release](https://github.com/RaredonLab/NICHESv2/releases/tag/data-v1) of the +NICHESv2 repository, and `download_NICHESv2_data()` fetches them. Each tutorial +calls it for you. The downloads are about 14 MB and 11 MB, happen once, and need +no other package. To fetch both now: ```r -remotes::install_github("satijalab/seurat-data") -SeuratData::InstallData("stxBrain") -SeuratData::InstallData("ifnb") +invisible(download_NICHESv2_data("stxBrain")) +invisible(download_NICHESv2_data("ifnb")) ``` ## 4. Run the tutorials @@ -76,6 +76,8 @@ stores 605,973. ## 5. Explore further +- [Starting from a Seurat object](seurat-objects.html) shows how the tutorial + inputs were made from Seurat objects. It needs SeuratData and Seurat. - [Input formats](input-formats.html) shows how to use your own data. - [The NICHESObject](niches-object.html) explains each slot. - [Neighborhood aggregation](aggregation.html) explains the 27 aggregation columns @@ -85,7 +87,9 @@ stores 605,973. ## If something goes wrong -- **A download fails:** the data are served by the Satija Lab. Try again later. +- **A download fails:** check your internet connection and try again. The files + are listed on the + [release page](https://github.com/RaredonLab/NICHESv2/releases/tag/data-v1). - **A step runs out of memory:** close other programs. The non-spatial tutorial needs about 4 GB. - **A step feels slow:** raise `n.cores` if your computer has more cores. diff --git a/vignettes/articles/nonspatial-tutorial.Rmd b/vignettes/articles/nonspatial-tutorial.Rmd index e8d5891..a27bb3d 100644 --- a/vignettes/articles/nonspatial-tutorial.Rmd +++ b/vignettes/articles/nonspatial-tutorial.Rmd @@ -33,46 +33,25 @@ memory. ## Get the data -The dataset comes from [SeuratData](https://github.com/satijalab/seurat-data), -which isn't on CRAN. Run this once; the download is about 413 MB. SeuratData also -installs the Seurat package, so the first install can take a while. - -```{r install, eval = FALSE} -install.packages(c("remotes", "SeuratObject")) -remotes::install_github("satijalab/seurat-data") -SeuratData::InstallData("ifnb") -``` +`download_NICHESv2_data()` fetches the dataset from a NICHESv2 release on GitHub, +so you don't need any other package. The download is about 11 MB and happens +once; later calls read the saved copy. ```{r load} library(NICHESv2) library(data.table) library(ggplot2) -library(SeuratObject) -library(SeuratData) - -data("ifnb") -``` -SeuratData objects keep the Seurat version they were saved with. -`extract_NICHESInputs_Seurat()` reads both V4 and V5 objects, so you don't need -to update them first. - -## Extract the inputs - -```{r extract} -inputs <- extract_NICHESInputs_Seurat( - seurat.obj = ifnb, - assay = "RNA", - layer = "counts", - verbose = FALSE -) +inputs <- download_NICHESv2_data("ifnb", verbose = FALSE) dim(inputs$count.mtx) table(inputs$meta.data$stim) ``` -Two metadata columns matter here: `stim` holds the condition, and -`seurat_annotations` holds 13 cell types. +`inputs` holds the raw counts as a sparse genes x cells matrix, and the cell +metadata. Two metadata columns matter here: `stim` holds the condition, and +`seurat_annotations` holds 13 cell types. To prepare the same inputs from a +Seurat object, see [Starting from a Seurat object](seurat-objects.html). ## Build the NICHESObject @@ -177,3 +156,8 @@ values with care. The data are from Kang HM, Subramaniam M, Targ S, et al. Multiplexed droplet single-cell RNA-sequencing using natural genetic variation. *Nat Biotechnol*. 2018;36(1):89-94 (GEO: GSE96583). Cell-type labels are from the Satija Lab. +NICHESv2 hosts a copy taken from the `ifnb` object in the SeuratData package +`ifnb.SeuratData`, under its +[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license. The copy keeps +the raw counts and cell metadata unchanged. The `PROVENANCE.md` file that comes +with the download gives the details. diff --git a/vignettes/articles/seurat-objects.Rmd b/vignettes/articles/seurat-objects.Rmd new file mode 100644 index 0000000..36f4e21 --- /dev/null +++ b/vignettes/articles/seurat-objects.Rmd @@ -0,0 +1,115 @@ +--- +title: "Starting from a Seurat object" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Starting from a Seurat object} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r setup, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, comment = "#>", message = FALSE, + render = function(x, ...) { + if (data.table::is.data.table(x) && !data.table::shouldPrint(x)) return(invisible("")) + if (is.data.frame(x)) x <- knitr::kable(x, digits = 3, format.args = list(big.mark = ",")) + knitr::knit_print(x, ...) + } +) +# The code runs only when SeuratData and both datasets are installed, so the +# rest of the website still builds if they are unavailable. +has.seuratdata <- requireNamespace("SeuratObject", quietly = TRUE) && + requireNamespace("SeuratData", quietly = TRUE) && + all(c("stxBrain.SeuratData", "ifnb.SeuratData") %in% + rownames(utils::installed.packages())) +knitr::opts_chunk$set(eval = has.seuratdata) +``` + +```{r notice, echo = FALSE, results = "asis", eval = !has.seuratdata} +cat("> **Note:** this copy of the page was built without SeuratData, so the code", + "below shows no output.\n") +``` + +Most single-cell data in R lives in Seurat objects. This page shows how +`extract_NICHESInputs_Seurat()` turns two real Seurat objects into NICHESv2 +inputs. They are the same two datasets the tutorials use, and these are the steps +that made the tutorial inputs. + +The objects come from [SeuratData](https://github.com/satijalab/seurat-data), +which the Satija Lab maintains. The tutorials don't need it, because they +download the finished inputs with `download_NICHESv2_data()`. + +## Install SeuratData + +SeuratData isn't on CRAN. Run this once; the downloads are about 143 MB for +`stxBrain` and 413 MB for `ifnb`. SeuratData also installs the Seurat package, so +the first install can take a while. + +```{r install, eval = FALSE} +install.packages(c("remotes", "SeuratObject")) +remotes::install_github("satijalab/seurat-data") +SeuratData::InstallData(c("stxBrain", "ifnb")) +``` + +```{r load} +library(NICHESv2) +library(SeuratObject) +library(SeuratData) +``` + +SeuratData objects keep the Seurat version they were saved with. +`extract_NICHESInputs_Seurat()` reads both V4 and V5 objects, so you don't need +to update them first. The spatial object below is V5 and the non-spatial one is +V4. + +## A spatial object: Visium mouse brain + +`stxBrain` holds four sections, and the spatial tutorial uses `anterior1`. + +```{r spatial} +data("anterior1") + +spatial <- extract_NICHESInputs_Seurat( + seurat.obj = anterior1, + assay = "Spatial", + layer = "counts", + verbose = FALSE +) +dim(spatial$count.mtx) +``` + +Spatial coordinates sit in the image part of the Seurat object, so add them to +the metadata as `x` and `y`. Matching by barcode keeps every spot aligned. + +```{r coords} +coords <- GetTissueCoordinates(anterior1) +spatial$meta.data$x <- coords[rownames(spatial$meta.data), "x"] +spatial$meta.data$y <- coords[rownames(spatial$meta.data), "y"] +head(spatial$meta.data[, c("x", "y")], 3) +``` + +## A non-spatial object: stimulated PBMCs + +```{r nonspatial} +data("ifnb") + +nonspatial <- extract_NICHESInputs_Seurat( + seurat.obj = ifnb, + assay = "RNA", + layer = "counts", + verbose = FALSE +) +dim(nonspatial$count.mtx) +table(nonspatial$meta.data$stim) +``` + +No coordinates are needed here, because non-spatial mode pairs cells by sampling +within cell types. + +## Next steps + +`spatial` and `nonspatial` hold the same inputs that `download_NICHESv2_data()` +returns. Pass either to `create_NICHESObject()` and continue with the +[spatial tutorial](spatial-tutorial.html) or the +[non-spatial tutorial](nonspatial-tutorial.html). For other Seurat options, such +as choosing a layer, see [Input formats](input-formats.html). diff --git a/vignettes/articles/spatial-tutorial.Rmd b/vignettes/articles/spatial-tutorial.Rmd index 4198d45..03284b8 100644 --- a/vignettes/articles/spatial-tutorial.Rmd +++ b/vignettes/articles/spatial-tutorial.Rmd @@ -28,52 +28,23 @@ With `n.cores = 2`, the slowest step takes about 4 minutes. ## Get the data -The dataset comes from [SeuratData](https://github.com/satijalab/seurat-data), -which isn't on CRAN. Run this once; the download is about 143 MB. SeuratData also -installs the Seurat package, so the first install can take a while. - -```{r install, eval = FALSE} -install.packages(c("remotes", "SeuratObject")) -remotes::install_github("satijalab/seurat-data") -SeuratData::InstallData("stxBrain") -``` - -Then load it. `stxBrain` holds four sections, and we use `anterior1`. +`download_NICHESv2_data()` fetches the dataset from a NICHESv2 release on GitHub, +so you don't need any other package. The download is about 14 MB and happens +once; later calls read the saved copy. ```{r load} library(NICHESv2) library(data.table) library(ggplot2) -library(SeuratObject) -library(SeuratData) - -data("anterior1") -``` - -SeuratData objects keep the Seurat version they were saved with. -`extract_NICHESInputs_Seurat()` reads both V4 and V5 objects, so you don't need -to update them first. -## Extract the inputs - -```{r extract} -inputs <- extract_NICHESInputs_Seurat( - seurat.obj = anterior1, - assay = "Spatial", - layer = "counts", - verbose = FALSE -) +inputs <- download_NICHESv2_data("stxBrain", verbose = FALSE) dim(inputs$count.mtx) ``` -Spatial coordinates sit in the image part of the Seurat object, so add them to -the metadata as `x` and `y`. Matching by barcode keeps every spot aligned. - -```{r coords} -coords <- GetTissueCoordinates(anterior1) -inputs$meta.data$x <- coords[rownames(inputs$meta.data), "x"] -inputs$meta.data$y <- coords[rownames(inputs$meta.data), "y"] -``` +`inputs` holds the raw counts as a sparse genes x spots matrix, and the spot +metadata, which already has each spot's coordinates in `x` and `y`. To prepare +the same inputs from a Seurat object, see +[Starting from a Seurat object](seurat-objects.html). ## Choose a neighborhood @@ -235,4 +206,8 @@ unlink(out.file) The data are from 10x Genomics, "Mouse Brain Serial Section 1 (Sagittal-Anterior)", Space Ranger 1.0.0, licensed under -[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). +[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). NICHESv2 hosts a copy +taken from the `anterior1` object in the SeuratData package `stxBrain.SeuratData`. +The copy keeps the raw counts and spot metadata unchanged, and adds the spot +coordinates. The `PROVENANCE.md` file that comes with the download gives the +details. diff --git a/working-scripts-NW/v1_facts_sheet.md b/working-scripts-NW/v1_facts_sheet.md index 5e4b4c9..48328ab 100644 --- a/working-scripts-NW/v1_facts_sheet.md +++ b/working-scripts-NW/v1_facts_sheet.md @@ -117,7 +117,8 @@ Runs below used raw counts, `method = "product"`, the default database and | | `stxBrain` (anterior1) | `ifnb` | |---|---|---| | Size | 31,053 genes x 2,696 spots | 14,053 genes x 13,999 cells | -| Download | 143 MB | 413 MB | +| Download with `download_NICHESv2_data()` | 13.9 MB | 11.1 MB | +| Download with SeuratData | 143 MB | 413 MB | | Mode | spatial, `k = 6`, mouse | nonspatial, human | | Other settings | assay `"Spatial"` | `sample.col = "stim"`, `cell.type.col = "seurat_annotations"` | | Scored rows in `$edge.data` | 5,191,520 | 605,973 | @@ -125,12 +126,19 @@ Runs below used raw counts, `method = "product"`, the default database and | Aggregate | about 12 s | not run | | TissuePlex export | about 4 s | not run | -- Both datasets come from SeuratData, which isn't on CRAN. NICHESv2 hosts no - data. Install with `remotes::install_github("satijalab/seurat-data")`, then - `SeuratData::InstallData("stxBrain")` and `SeuratData::InstallData("ifnb")`. - SeuratData imports Seurat, so installing it also installs Seurat. NICHESv2 - itself only needs SeuratObject to read Seurat objects. SeuratData stays out of - `DESCRIPTION`. +- Decision 2026-11-03: NICHESv2 hosts both datasets itself, so the website + doesn't depend on the Satija Lab. `data-raw/build_tutorial_data.R` builds + `stxBrain.zip` and `ifnb.zip` (each `inputs.rds` plus `PROVENANCE.md`) and a + `SHA256SUMS` file. They are attached to the GitHub release `data-v1` of + RaredonLab/NICHESv2, and `download_NICHESv2_data()` fetches them, checks the + MD5 sum and caches them. The inputs are identical to a fresh + `extract_NICHESInputs_Seurat()` run on the SeuratData objects (checked + 2026-11-03). +- Only the "Starting from a Seurat object" page uses SeuratData. Install with + `remotes::install_github("satijalab/seurat-data")`, then + `SeuratData::InstallData(c("stxBrain", "ifnb"))`. SeuratData imports Seurat, + so installing it also installs Seurat. NICHESv2 itself only needs SeuratObject + to read Seurat objects. SeuratData stays out of `DESCRIPTION`. - `UpdateSeuratObject()` is not needed. `extract_NICHESInputs_Seurat()` gives identical results with or without it on both datasets (SeuratObject 5.0.2 and 5.1.0). SeuratData objects keep their own Seurat version: `ifnb` is a V4-style @@ -153,6 +161,8 @@ Runs below used raw counts, `method = "product"`, the default database and - `ifnb` comes from Kang et al., Nat Biotechnol 2018;36(1):89-94 (GSE96583), with cell-type labels added by the Satija Lab. The `ifnb.SeuratData` package is labeled CC BY 4.0, but no license from the original authors was found. +- Decision 2026-11-03: rehost both under CC BY 4.0 with credit, the source + package version and the changes stated in each `PROVENANCE.md`. ## TissuePlex