Human Tumor Atlas Network data in R, as Bioconductor objects, without a Google account.
The Human Tumor Atlas Network (HTAN) is an NCI Cancer Moonshot consortium building single-cell and spatial atlases of how tumors start, grow, spread and resist treatment. Phase 1 has 14 atlases and more than 220,000 data files (single-cell sequencing, multiplexed and electron microscopy imaging, spatial transcriptomics and bulk assays), with clinical and biospecimen data linking each file to the participants it came from.
This package lets you find those files, trace where each came from,
download the open ones and read them into SingleCellExperiment,
SpatialExperiment and MultiAssayExperiment objects. The metadata comes
from a versioned parquet snapshot that you query locally with dplyr through
DuckDB. Outside this package, the queryable HTAN metadata tables are
published in Google BigQuery, which needs a Google account and a billing
project. Here, a fresh R session or a Bioconductor build machine can query
all of HTAN Phase 1 anonymously.
HTAN is not yet on Bioconductor. Until it is, install the development version from GitHub:
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("seandavi/HTAN")
Once the package is accepted, install it from Bioconductor instead:
BiocManager::install("HTAN")
library(HTAN)
library(dplyr)
con <- htan_con("r7") # ~20 MB from Hugging Face, once; then cached
htan_files() |> count(access) # 221,688 files by where you can get them
scrna <- htan_files(assay == "ScRNA-seq", level == 4)
scrna |> count(HTAN_Center, sort = TRUE)
htan_lineage(head(scrna, 1)) |> collect() # back to raw files and biospecimens
img <- htan_files(access == "open-gc", File_Size < 1e6) |> head(1)
dl <- htan_download(img) # anonymous, no account; cached
Every query returns a lazy table. You filter, join and count it with dplyr,
and nothing is computed until you collect() it. htan_download() checks
each file's md5 and keeps it in a BiocFileCache under
tools::R_user_dir("HTAN", "cache"), so a second request for the same file
costs nothing; pass dest to also copy the files to a directory of your
choice. read_htan() turns downloaded files into Bioconductor objects, and
htan_experiment() assembles several of them into a MultiAssayExperiment
with participant clinical data as colData.
| Data | Where it lives | What you need |
|---|---|---|
| All metadata: files, clinical, biospecimen, provenance (78 tables) | The parquet snapshot | Nothing |
Open Level 2 imaging (access == "open-gc", about 24,000 files) |
CRDC General Commons, anonymous GA4GH DRS | Nothing |
Open Level 3/4 processed data, auxiliary files ("open-synapse", about 155,000) |
Synapse | A free Synapse account and a personal access token in SYNAPSE_AUTH_TOKEN
|
Level 1/2 sequencing ("controlled", about 43,000) |
dbGaP phs002371 | Out of scope; htan_download() refuses these |
| HTAN Phase 2 | Not yet released through ISB-CGC | Out of scope for now |
The snapshot is the public Hugging Face dataset
seandavis/htan, one git
tag per HTAN release. Tag r7 holds Release 7, the final Phase 1 release:
78 parquet files (821,773 rows, 19.8 MB) and a manifest.json that records
each table's source, row count, columns and sha256. htan_con() downloads
the files once, checks every sha256 before caching them with BiocFileCache,
and opens one DuckDB view per table.
A maintainer-only builder in
inst/scripts/build_snapshot exports the
ISB-CGC HTAN BigQuery release tables, each from its
pinned, versioned copy. You don't have to go through
the package to use the snapshot. You can browse the dataset on Hugging Face
or read it from DuckDB directly
(hf://datasets/seandavis/htan@r7/<table>.parquet). Within the package,
options(HTAN.base_url = ...) points it at a mirror or a local build, and a
tiny fixture snapshot ships with the package for examples and tests. The
design is recorded in adr/.
id_provenance, and the pitfalls in the r7 metadata.SpatialExperiment in a
MultiAssayExperiment.The articles are also installed as vignettes (browseVignettes("HTAN")),
and the function reference is
on the same site.
Version 0.99.x, experimental. The snapshot build, the Hugging Face default, anonymous DRS downloads and Synapse downloads with a personal access token have been verified against the live services (#7). The readers have been tested on synthetic and example data but not yet systematically on real HTAN Level 4 files (#8).
An AI coding agent, Claude Code
(Anthropic), wrote almost all of the code, tests, documentation and
vignettes, working from the maintainer's design and under the maintainer's
direction and review. The maintainer set the architecture (recorded in
adr/), chose the data sources and the scope, reviewed the work,
and is responsible for the package, its correctness and its maintenance.
Each commit written with the agent carries a Co-Authored-By: trailer, so
git log records the provenance of every change. The offline test suite,
R CMD check and BiocCheck run on every pull request, and live integration
tests against the HTAN services run weekly. No third-party code was copied
into the package, and everything here is released under the package's MIT
license. CONTRIBUTING.md
describes how agent-assisted work is reviewed.
If you use the package, please cite it and the HTAN consortium paper;
citation("HTAN") gives both.
Rozenblatt-Rosen O, Regev A, Oberdoerffer P, et al. The Human Tumor Atlas Network: Charting Tumor Transitions across Space and Time at Single-Cell Resolution. Cell 2020;181(2):236–249. doi:10.1016/j.cell.2020.03.053
Ask usage questions on the Bioconductor support
site with the tag htan, and report bugs
in the issue tracker. Contributions
are welcome: CONTRIBUTING.md covers the development setup,
the tests and the snapshot builder. Please follow the code of
conduct.
Developed with support from NCI grant U24CA289073. HTAN data are generated by the HTAN research centers and coordinated by the HTAN Data Coordinating Center; the metadata tables are published by the ISB Cancer Gateway in the Cloud (ISB-CGC).