Read 10X Visium data as SpatialFeatureExperiment

Read Space Ranger output from Visium v1 (not HD) as a SpatialFeatureExperiment object, where spots are represented with polygons in the colGeometry called "spotPoly". Other geometries can be added later after the dataset is read. If data = "filtered", then spatial neighborhood graphs of the spots are also computed and stored in the colGraph called "visium" in all samples for downstream spatial analyses.

Usage

read10xVisiumSFE(
  samples = "",
  dirs = file.path(samples, "outs"),
  sample_id = paste0("sample", sprintf("%02d", seq_along(samples))),
  type = c("HDF5", "sparse"),
  data = c("filtered", "raw"),
  images = c("lowres", "hires"),
  unit = c("full_res_image_pixel", "micron"),
  style = "W",
  zero.policy = NULL,
  load = deprecated(),
  row.names = c("id", "symbol"),
  flip = c("geometry", "image", "none")
)

Arguments

samples

A character vector containing one or more directory names, each corresponding to a 10X sample. Each directory should contain a matrix file, a gene/feature annotation file, and a barcode annotation file.

Alternatively, each string may contain a path to a HDF5 file in the sparse matrix format generated by 10X. These can be mixed with directory names when type="auto".

Alternatively, each string may contain a prefix of names for the three-file system described above, where the rest of the name of each file follows the standard 10X output.

dirs

Directory for each sample that contains the spatial and raw/filtered_featues_bc_matrix directories. By default, the outs directory under the directory specified in the samples argument, as in Space Ranger output. Change the dirs argument if you have moved or renamed the output directory.

sample_id

Which sample(s) in the SFE object to use for the graph. Can also be "all", which means this function will compute the graph for all samples independently.

type

Either "HDF5", and the matrix will be represented as TENxMatrix, or "sparse", and the matrix will be read as a dgCMatrix.

data

character string specifying whether to read in filtered (spots mapped to tissue) or raw data (all spots).

images

character vector specifying which images to include. Valid values are "lowres", "hires", "fullres", "detected", "aligned"

unit

Whether to use pixels in full resolution image or microns as the unit. If using microns, then spacing between spots in pixels will be used to convert the coordinates into microns, as the spacing is known to be 100 microns. This is used to plot scale bar.

style

style can take values “W”, “B”, “C”, “U”, “minmax” and “S”

zero.policy

default NULL, use global option value; if FALSE stop with error for any empty neighbour sets, if TRUE permit the weights list to be formed with zero-length weights vectors

load

Deprecated. Not used, kept for backward compatibility for now.

row.names

String specifying whether to use Ensembl IDs ("ID") or gene symbols ("Symbol") as row names. If using symbols, the Ensembl ID will be appended to disambiguate in case the same symbol corresponds to multiple Ensembl IDs.

flip

Whether to flip the geometries or the images, because in sf and terra, the geometries use the Cartesian coordinates greater y coordinates going up, while in images, greater y values go down. Originally the Visium spots are in pixels in full res image. Either the image or the geometry needs to be flipped for them match in the Cartesian coordinate system.

sample

To be consistent with SpatialExperiment::read10xVisium, one or more directories with Space Ranger output for a Visium sample. It is assumed to have the outs directory in it but this can be overridden with the dirs argument.

Value

A SpatialFeatureExperiment object. The images might need to be manually transposed and/or mirrored to match the spots in this version of this package.

Note

It is assumed that the images have not been cropped. Otherwise the images might not align with the spots.

Examples

dir <- system.file("extdata", package = "SpatialFeatureExperiment")

sample_ids <- c("sample01", "sample02")
samples <- file.path(dir, sample_ids)

list.files(samples[1])
#> [1] "outs"
list.files(file.path(samples[1], "spatial"))
#> character(0)
(sfe <- read10xVisiumSFE(samples, sample_id = sample_ids,
    type = "sparse", data = "filtered",
    load = FALSE
))
#> Warning: The `load` argument of `read10xVisiumSFE()` is deprecated as of
#> SpatialFeatureExperiment 1.8.0.
#> >>> 10X Visium data will be loaded: outs
#> >>> Adding spatial neighborhood graph to sample01
#> >>> 10X Visium data will be loaded: outs
#> >>> Adding spatial neighborhood graph to sample02
#> class: SpatialFeatureExperiment 
#> dim: 5 25 
#> metadata(0):
#> assays(1): counts
#> rownames(5): ENSG00000014257 ENSG00000142515 ENSG00000263639
#>   ENSG00000163810 ENSG00000149591
#> rowData names(14): symbol Feature.Type ...
#>   Median.Normalized.Average.Counts_sample02
#>   Barcodes.Detected.per.Feature_sample02
#> colnames(25): GTGGCGTGCACCAGAG-1 GGTCCCATAACATAGA-1 ...
#>   TGCAATTTGGGCACGG-1 ATGCCAATCGCTCTGC-1
#> colData names(10): in_tissue array_row ... channel3_mean channel3_stdev
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : pxl_col_in_fullres pxl_row_in_fullres
#> imgData names(4): sample_id image_id data scaleFactor
#> 
#> unit: full_res_image_pixel
#> Geometries:
#> colGeometries: spotPoly (POLYGON) 
#> 
#> Graphs:
#> sample01: col: visium
#> sample02: col: visium