This function initiates a SPATA2 object with data generated using the 10x Genomics Visium platform.

initiateSpataObjectVisium(
  sample_name,
  directory_visium,
  mtr = "filtered",
  img_active = "lowres",
  img_ref = "hires",
  resize_images = NULL,
  unload = TRUE,
  verbose = TRUE
)

Arguments

sample_name

Character. The name of the sample.

directory_visium

Character. The directory containing the Visium output files.

mtr

Character. Specifies which matrix to use, either "filtered" or "raw". Default is "filtered".

img_active

Character. The active image to use, either "lowres" or "hires". Default is "lowres".

img_ref

Character. The reference image to use, either "lowres" or "hires". Default is "hires".

resize_images

A named list of numeric values between 0-1 used to resize the respective image as indicated by the slot name. E.g resize_images = list(hires = 0.5) resizes the hires image to 50% of its original scale.

unload

Logical value. If TRUE, every image except for the active image is unloaded.

verbose

Logical. If TRUE, informative messages regarding the computational progress will be printed.

(Warning messages will always be printed.)

Value

A SPATA2 object containing data from the Visium platform. More precise, depending on the set up used to create the raw data it is of either spatial method:

  • VisiumSmall: Visium data set with capture area of 6.5mm x 6.5mm.

  • VisiumLarge: Visium data set with capture area of 11mm x 11m.

In any case, the output is an object of class SPATA2.

Details

The function requires a directory containing the output files from a 10x Genomics Visium experiment specified with the argument directory_visum. This directory (below denoted as ~) must include the following files and sub-directories:

  • ~/filtered_feature_bc_matrix.h5 or raw_feature_bc_matrix.h5: The HDF5 file containing the filtered or raw feature-barcode matrix, respectively.

  • ~/spatial/tissue_lowres_image.png or spatial/tissue_hires_image.png: The low-resolution or high-resolution tissue image.

  • ~/spatial/scalefactors_json.json: A JSON file containing the scale factors for the images.

  • ~/spatial/tissue_positions_list.csv or /~spatial/tissue_positions.csv: A CSV file containing the tissue positions and spatial coordinates.

The function will check for these files and process them to create a SPATA2 object. It reads the count matrix, loads the spatial data, and initializes the SPATA2 object with the necessary metadata and settings.

Gene and Protein Expression

This function also supports reading coupled gene expression and protein expression data. It expects the input directory to contain an HDF5 file that includes separate datasets for gene expression and protein expression. The function uses Seurat::Read10X_h5() with unique.features = TRUE, to read in data and, if the result is a list, it assumes that it contains gene and protein expression. This scenario is handled as follows:

  • Gene expression data is extracted from the "Gene Expression" dataset in the HDF5 file and stored in an assay named gene.

  • Protein expression data is extracted from the "Antibody Capture" dataset in the HDF5 file protein.

The function ensures that molecule names do not overlap by normalizing the names:

  • Gene expression molecule names remain in upper case (human data) or title case (mouse data).

  • Protein expression molecule names are forced to lowercase.

This naming convention prevents any overlap and ensures that each molecule type is uniquely identified in the resulting SPATA2 object, which contains two assays. One of molecular modality gene and of of molecular modality protein.

Row and column indices

Visium spot coordinates come with column and row indices. The functions initiateSpataObjectVisium() and initiateSpataObjectVisiumHD() ensure that col aligns with the direction of the x-coordinates and that row aligns with the direction of the y-coordinates. If they do not, they are adjusted accordingly. Hence, these variables should not be used as keys for data merging.

See also

flipAll() to revert the effect of a horizontally flipped sample. (SPATA2 works in cartesian coordinate system, in which images are displayed, too. Therefore, samples are displayed "upside-down" when compared to the image in your folder.)