Read an HTAN file into a Bioconductor object

Dispatches on the file extension (HTAN's File_Format is too coarse: hdf5 covers .h5ad and 10x .h5, RData covers .rds):

Usage

read_htan(x, coords = NULL, ...)

Arguments

x: A file path, a Space Ranger outs/ directory, or the result of htan_download() (in which case every row's path is read).
coords: character(2) or NULL. For cell tables, the x and y centroid columns. NULL tries common names (X_centroid/ Y_centroid from MCMICRO, x/y, centroid_x/centroid_y, and others).
...: Passed to the underlying reader.

Value

A SingleCellExperiment, SpatialExperiment, other SummarizedExperiment, tibble or path, depending on the file. For a multi-row htan_download() result, a list named by HTAN_Data_File_ID.

Details

.h5ad: anndataR::read_h5ad() to a SingleCellExperiment; a spatial embedding becomes spatialCoords() of a SpatialExperiment. Files in the pre-0.8 AnnData layout, which anndataR rejects and many HTAN centers wrote, are read with rhdf5 instead: X, layers, obs, var and numeric obsm arrays, but not uns. Duplicated obs or var names are made unique with make.unique(), with a message.
.rds, .rda, .RData: Read, then: SingleCellExperiment and other SummarizedExperiments pass through; a Seurat object is converted with SeuratObject (counts, data, metadata, reductions, and tissue coordinates when present). Anything else is returned as is, with a message.
.h5 (10x): TENxIO::TENxH5() to a SingleCellExperiment.
a Space Ranger outs/ directory: VisiumIO::TENxVisium() to a SpatialExperiment.
.csv, .tsv, .txt (optionally .gz): Imaging Level 4 cell tables become a SpatialExperiment (cells as columns, marker intensities as the intensities assay, centroids as spatialCoords(), other per-cell columns as colData). A table without recognisable coordinates is returned as a tibble.
.tif, .tiff, .svs: Images are not read; the path is returned with a message (see RBioFormats or cytomapper).

Level 4 objects are heterogeneous across HTAN centers. Readers are best-effort: check the result.

Examples

cells <- data.frame(CellID = 1:3, CD3 = c(1, 5, 2), CD8 = c(0, 3, 1),
    X_centroid = c(10, 20, 30), Y_centroid = c(5, 15, 25), Area = 40:42)
path <- tempfile(fileext = ".csv")
write.csv(cells, path, row.names = FALSE)
read_htan(path)
#> class: SpatialExperiment 
#> dim: 2 3 
#> metadata(0):
#> assays(1): intensities
#> rownames(2): CD3 CD8
#> rowData names(0):
#> colnames(3): 1 2 3
#> colData names(3): CellID Area sample_id
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : x y
#> imgData names(0):

## A tiny Visium file in the pre-0.8 AnnData layout
if (requireNamespace("rhdf5", quietly = TRUE)) {
    read_htan(system.file("extdata", "h5ad", "legacy_visium.h5ad",
        package = "HTAN"))
}
#> legacy_visium.h5ad is in the pre-0.8 AnnData layout; reading it with read_htan()'s fallback reader.
#> ℹ `uns` is not read; `...` is ignored.
#> class: SpatialExperiment 
#> dim: 5 4 
#> metadata(0):
#> assays(3): counts dense X
#> rownames(5): OR4F5 SAMD11 NOC2L KLHL17 PERM1
#> rowData names(5): gene_ids feature_types highly_variable n_cells
#>   Feature.Counts.in.Spots.Under.Tissue
#> colnames(4): AAACAAGTATCTCCCA-1 AAACAATCTACTAGCA-1 AAACACCAATAACTGC-1
#>   AAACAGAGCGACTCCT-1
#> colData names(6): in_tissue array_row ... cluster sample_id
#> reducedDimNames(1): X_pca
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : x y
#> imgData names(0):