Read Space Ranger output 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))),
bin_size = NULL,
type = c("HDF5", "sparse"),
data = c("filtered", "raw"),
images = c("lowres", "hires"),
unit = c("full_res_image_pixel", "micron"),
add_Graph = TRUE,
style = "W",
zero.policy = NULL,
load = FALSE,
row.names = c("id", "symbol")
)
Arguments
- samples
a character vector specifying one or more directories, each corresponding to a 10x Genomics Visium sample (see Details); if provided, names will be used as sample identifiers
- dirs
Directory for each sample that contains the
spatial
andraw/filtered_featues_bc_matrix
directories. By default, theouts
directory under the directory specified in thesamples
argument, as in Space Ranger output. Change thedirs
argument if you have moved or renamed the output directory.- sample_id
character string specifying unique sample identifiers, one for each directory specified via
samples
; ignored if!is.null(names(samples))
- bin_size
c(character)
, use this only when loading VisiumHD. Specify which bin resolution to load, default isNULL
which assumes that data is standard Visium. Eg, single resolution isc("8")
, if to load all three resolutions, usec("2", "8", "16")
.- type
Either "HDF5", and the matrix will be represented as
TENxMatrix
, or "sparse", and the matrix will be read as adgCMatrix
.- 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.
- add_Graph
c(local)
, if to add spatial neighborhood graph for spots and only ifc(data = "filtered")
. Default isc(TRUE)
- 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
Not used, kept for backward compatibility.
- 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.
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
The as(<dgTMatrix>, "dgCMatrix") is deprecated
warning comes
from the DropletUtils
package which is used by
SpatialExperiment
to read 10X outputs. This will be fixed when
SpatialExperiment
switches to TENxIO.
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
))
#> >>> 10X Visium data will be loaded: sample01
#> >>> Adding spatial neighborhood graph to sample01
#> >>> 10X Visium data will be loaded: sample02
#> >>> 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
# load VisiumHD
# path to "binned_outputs" directory containing:
# └── binned_outputs
# ├── square_002um
# ├── square_008um
# └── square_016um
dir_hd <- "~/Downloads/Visium_HD_Mouse_Brain/binned_outputs/"
# this is public dataset ->
# https://www.10xgenomics.com/datasets/visium-hd-cytassist-gene-expression-libraries-of-mouse-brain-he
sfe_hd <-
read10xVisiumSFE(samples = list.files(dir_hd), # 1:3 resolutions
dirs = dir_hd,
bin_size = c("8", "16"), # this defines which of 1:3 resolutions to load
type = "HDF5", # Note, "sparse" -> takes longer to load
data = "filtered", # spots under tissue
images = c("lowres"), # for now low res. image only
add_Graph = FALSE # Note, if VisiumHD this can take time for 2 or 8µm res.
)