Creating a TENxVisium instance

Using the example data from SpatialExperiment, we can load the section1 sample using TENxVisium.

outs_folder <- system.file(
    file.path("extdata", "10xVisium", "section1", "outs"),
    package = "VisiumIO"
)

vis <- TENxVisium(
    spacerangerOut = outs_folder, processing = "raw", images = "lowres"
)
vis

## An object of class "TENxVisium"
## Slot "resources":
## TENxFileList of length 3
## names(3): barcodes.tsv features.tsv matrix.mtx
## 
## Slot "spatialList":
## TENxSpatialList of length 3
## names(3): scalefactors_json.json tissue_lowres_image.png tissue_positions_list.csv
## 
## Slot "coordNames":
## [1] "pxl_col_in_fullres" "pxl_row_in_fullres"
## 
## Slot "sampleId":
## [1] "sample01"

Note that the spacerangerOut input corresponds directly to the outs folder from the spaceranger output.

The show method of the TENxVisium class displays the object’s metadata.

Importing into SpatialExperiment

The TEnxVisium object can be imported into a SpatialExperiment object using the import function.

import(vis)

## class: SpatialExperiment 
## dim: 50 50 
## metadata(2): resources spatialList
## assays(1): counts
## rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
##   ENSMUSG00000005886 ENSMUSG00000101476
## rowData names(3): ID Symbol Type
## colnames(50): AAACAACGAATAGTTC-1 AAACAAGTATCTCCCA-1 ...
##   AAAGTCGACCCTCAGT-1 AAAGTGCCATCAATTA-1
## colData names(4): in_tissue array_row array_col sample_id
## reducedDimNames(0):
## mainExpName: Gene Expression
## altExpNames(0):
## spatialCoords names(2) : pxl_col_in_fullres pxl_row_in_fullres
## imgData names(4): sample_id image_id data scaleFactor

Creating a TENxVisiumList

The main inputs to TENxVisiumList are the sampleFolders and sample_ids. These correspond to the spaceranger output sample folders and a vector of sample identifiers, respectively.

sample_dirs <- list.dirs(
    system.file(
        file.path("extdata", "10xVisium"), package = "VisiumIO"
    ),
    recursive = FALSE, full.names = TRUE
)
    
vlist <- TENxVisiumList(
    sampleFolders = sample_dirs,
    sample_ids = basename(sample_dirs),
    processing = "raw",
    images = "lowres"
)
vlist

## An object of class "TENxVisiumList"
## Slot "VisiumList":
## List of length 2

Importing into SpatialExperiment

The import method combines both SingleCellExperiment objects along with the spatial information into a single SpatialExperiment object. The number of columns in the SpatialExperiment object is equal to the number of cells across both samples (section1 and section2).

import(vlist)

## class: SpatialExperiment 
## dim: 50 99 
## metadata(4): resources spatialList resources spatialList
## assays(1): counts
## rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
##   ENSMUSG00000005886 ENSMUSG00000101476
## rowData names(3): ID Symbol Type
## colnames(99): AAACAACGAATAGTTC-1 AAACAAGTATCTCCCA-1 ...
##   AAAGTCGACCCTCAGT-1 AAAGTGCCATCAATTA-1
## colData names(4): in_tissue array_row array_col sample_id
## reducedDimNames(0):
## mainExpName: Gene Expression
## altExpNames(0):
## spatialCoords names(2) : pxl_col_in_fullres pxl_row_in_fullres
## imgData names(4): sample_id image_id data scaleFactor

Visium HD folder structure

The directory structure for a single bin size is shown below.

    Visium_HD
    └── binned_outputs
        └─── square_002um
        │   └── filtered_feature_bc_matrix
        │   │   └── barcodes.tsv.gz
        │   │   └── features.tsv.gz
        │   │   └── matrix.mtx.gz
        │   └── filtered_feature_bc_matrix.h5
        │   └── raw_feature_bc_matrix/
        │   └── raw_feature_bc_matrix.h5
        │   └── spatial
        │       └── [ ... ]
        │       └── tissue_positions.parquet
        └── square_*

Import Visium HD into SpatialExperiment

TENxVisiumHD(
    spacerangerOut = "./Visium_HD/",
    sample_id = "sample01",
    processing = c("filtered", "raw"),
    images = c("lowres", "hires", "detected", "aligned_fiducials"),
    bin_size = c("002", "008", "016"),
    jsonFile = .SCALE_JSON_FILE,
    tissuePattern = "tissue_positions\\.parquet",
    spatialCoordsNames = c("pxl_col_in_fullres", "pxl_row_in_fullres"),
    ...
)

In-package example

By default, the MatrixMarket format is read in (format = "mtx").

visfold <- system.file(
    package = "VisiumIO", "extdata", mustWork = TRUE
)
TENxVisiumHD(
    spacerangerOut = visfold, images = "lowres", bin_size = "002"
) |> import()

## class: SpatialExperiment 
## dim: 10 10 
## metadata(2): resouces spatialList
## assays(1): counts
## rownames(10): ENSMUSG00000051951 ENSMUSG00000025900 ...
##   ENSMUSG00000033774 ENSMUSG00000025907
## rowData names(3): ID Symbol Type
## colnames(10): s_002um_02448_01644-1 s_002um_00700_02130-1 ...
##   s_002um_01016_02194-1 s_002um_00775_02414-1
## colData names(8): barcode in_tissue ... bin_size sample_id
## reducedDimNames(0):
## mainExpName: Gene Expression
## altExpNames(0):
## spatialCoords names(0) :
## imgData names(4): sample_id image_id data scaleFactor

H5 files are supported via the format = "h5" argument input.

TENxVisiumHD(
    spacerangerOut = visfold, images = "lowres", bin_size = "002",
    format = "h5"
) |> import()

## class: SpatialExperiment 
## dim: 10 10 
## metadata(2): resouces spatialList
## assays(1): counts
## rownames(10): ENSMUSG00000051951 ENSMUSG00000025900 ...
##   ENSMUSG00000033774 ENSMUSG00000025907
## rowData names(3): ID Symbol Type
## colnames(10): s_002um_02448_01644-1 s_002um_00700_02130-1 ...
##   s_002um_01016_02194-1 s_002um_00775_02414-1
## colData names(8): barcode in_tissue ... bin_size sample_id
## reducedDimNames(0):
## mainExpName: Gene Expression
## altExpNames(0):
## spatialCoords names(0) :
## imgData names(4): sample_id image_id data scaleFactor