Package 'SpatialFeatureExperiment'

Description

For adding the spot polygons to SFE objects converted from SPE.

Usage

addVisiumSpotPoly(x, spotDiameter)

Arguments

Value

A SFE object with a new colGeometry called spotPoly, which has polygons of the spots.

Examples

library(SpatialExperiment)
example(read10xVisium)
# There can't be suplicate barcodes
colnames(spe) <- make.unique(colnames(spe), sep = "-")
rownames(spatialCoords(spe)) <- colnames(spe)
sfe <- toSpatialFeatureExperiment(spe)
# A hypothetical spot diameter; check the scalefactors_json.json file for
# actual diameter in pixels in full resolution image.
sfe <- addVisiumSpotPoly(sfe, spotDiameter = 80)

Description

This function performs affine transformation on images, with any matrix and translation vector.

Usage

## S4 method for signature 'SpatRasterImage'
affineImg(x, M, v, maxcell = 1e+07, ...)

## S4 method for signature 'BioFormatsImage'
affineImg(x, M, v, ...)

## S4 method for signature 'ExtImage'
affineImg(x, M, v, ...)

Arguments

Value

SpatRasterImage will be converted to ExtImage. Otherwise *Image object of the same class. For BioFormatsImage, the transformation info is stored and will be applied when the image is loaded into memory as ExtImage.

See Also

Other image methods: SFE-image, cropImg(), dim,BioFormatsImage-method, ext(), imgRaster(), imgSource(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

To find the bounding box of multiple bounding boxes.

Usage

aggBboxes(bboxes)

Arguments

Value

A named numeric vector for the total bounding box.

Examples

bboxes <- list(c(xmin = 5, xmax = 10, ymin = 2, ymax = 20),
c(xmin = 8, xmax = 18, ymin = 0, ymax = 15))
bbox_all <- aggBboxes(bboxes)

Description

Gene expression and numeric columns of colData will be aggregated with the function specified in FUN, according to another geometry supplied and a geometry predicate (such as st_intersects). For example, when the predicate is st_intersects and a spatial grid is used to aggregate, then the data associated with all cells that intersect with each grid cell will be aggregated with FUN, such as mean or sum. The categorical columns will be collected into list columns, and logical columns will be converted into numeric before applying FUN.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
aggregate(
  x,
  by = NULL,
  FUN = sum,
  sample_id = "all",
  colGeometryName = 1L,
  rowGeometryName = NULL,
  cellsize = NULL,
  square = TRUE,
  flat_topped = FALSE,
  new_geometry_name = "bins",
  join = st_intersects,
  BPPARAM = SerialParam()
)

Arguments

Details

For smFISH-based data where the transcript spots are available, the transcript spots can be used instead of cells to aggregate the gene count matrix, in which case all assays other than counts will be dropped and FUN only applies to colData because the transcript spots are simply counted.

What this function does is similar to SEraster but more general because any geometry and more aggregation function can be used, not just regular grids, and the aggregation can be performed on the transcript spots.

Value

An SFE object with colGeometry the same as the geometry specified in by or same as the grid specified in cellsize. rowGeometries and rowData remain the same as in the input x. reducedDims, localResults, colFeatureData (and its colGeometry, annotGeometry, and reducedDim counterparts), and spatialGraphs are dropped because those results no longer apply after aggregation.

Note

For developers: When debugging this function after calling devtools::load_all("."), you may get an error that comes from S3 dispatch of aggregate.Vector from the S4Vectors package. When that happens, either restart the R session, or run setGeneric("aggregate", function(x, ...) standardGeneric("aggregate")) in the console to make an S4 generic as done in the terra package to prioritize S4 dispatch.

Examples

# example code

Description

This function reads the transcript spot file from the standard output of the commercial technologies (not GeoParquet) for spatial aggregation where the spots are assigned to polygons such as cells or spatial bins. Presets for Xenium, MERFISH, and CosMX are available. For Vizgen and Xenium, the images can be added when add_images = TRUE.

Usage

aggregateTx(
  file,
  df = NULL,
  by = NULL,
  sample_id = "sample01",
  spatialCoordsNames = c("X", "Y", "Z"),
  gene_col = "gene",
  phred_col = "qv",
  min_phred = 20,
  flip_geometry = FALSE,
  cellsize = NULL,
  square = TRUE,
  flat_topped = FALSE,
  new_geometry_name = "bins",
  unit = "micron"
)

aggregateTxTech(
  data_dir,
  df = NULL,
  by = NULL,
  tech = c("Vizgen", "Xenium", "CosMX"),
  sample_id = "sample01",
  image = NULL,
  min_phred = 20,
  flip = c("geometry", "image", "none"),
  max_flip = "50 MB",
  cellsize = NULL,
  square = TRUE,
  flat_topped = FALSE,
  new_geometry_name = "bins"
)

Arguments

Value

A SFE object with count matrix for number of spots of each gene in each geometry. Geometries with no spot are removed.

Note

The resulting SFE object often includes geometries (e.g. grid cells) outside tissue, because there can be transcript spots detected outside the tissue. Also, bins at the edge of the tissue that don't fully overlap with the tissue will have lower transcript counts; this may have implications to downstream spatial analyses.

Description

"Annotation geometry" refers to Simple Feature (sf) geometries NOT associated with rows (features, genes) or columns (cells or spots) of the gene count matrix in the SpatialFeatureExperiment object. So there can be any number of rows in the sf data frame specifying the geometry. Examples of such geometries are tissue boundaries, pathologist annotation of histological regions, and objects not characterized by columns of the gene count matrix (e.g. nuclei segmentation in a Visium dataset where the columns are Visium spots). This page documents getters and setters for the annotation geometries. Internally, annotation geometries are stored in int_metadata.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
annotGeometries(x)

## S4 replacement method for signature 'SpatialFeatureExperiment'
annotGeometries(x, translate = TRUE, ...) <- value

## S4 method for signature 'SpatialFeatureExperiment'
annotGeometryNames(x)

## S4 replacement method for signature 'SpatialFeatureExperiment,character'
annotGeometryNames(x) <- value

## S4 method for signature 'SpatialFeatureExperiment'
annotGeometry(x, type = 1L, sample_id = NULL)

## S4 replacement method for signature 'SpatialFeatureExperiment'
annotGeometry(x, type = 1L, sample_id = NULL, translate = TRUE, ...) <- value

tissueBoundary(x, sample_id = 1L)

tissueBoundary(x, sample_id = 1L, translate = TRUE, ...) <- value

Arguments

Details

Wrapper for getter and setter of special geometry:

tisseuBoundary

Boundary of the tissue of interest, including holes. This is usually of geometry type MULTIPOLYGON, though geometries in annotGeometries can have any type supported by sf.

Value

Getters for multiple geometries return a named list. Getters for names return a character vector of the names. Getters for single geometries return an sf data frame. Setters return an SFE object.

Examples

# Example dataset
library(SFEData)
sfe_small <- McKellarMuscleData(dataset = "small")

# Get all annotation geometries, returning a named list
annotGeometries(sfe_small)

# Set all annotation geometries, in a named list
toy <- readRDS(system.file("extdata/sfe_toy.rds",
    package = "SpatialFeatureExperiment"
))
ag <- readRDS(system.file("extdata/ag.rds",
    package = "SpatialFeatureExperiment"
))
annotGeometries(toy) <- list(hull = ag)

# Get names of annotation geometries
annotGeometryNames(sfe_small)

# Set names of annotation geometries
annotGeometryNames(toy) <- "foo"

# Get a specific annotation geometry by name
# sample_id is optional when there is only one sample present
nuclei <- annotGeometry(sfe_small, type = "nuclei", sample_id = "Vis5A")

# Get a specific annotation geometry by index
tb <- annotGeometry(sfe_small, type = 1L)

# Set a specific annotation geometry
annotGeometry(sfe_small, type = "nuclei2") <- nuclei

# Special convenience function for tissue boundaries
# Getter
tb <- tissueBoundary(sfe_small, sample_id = "Vis5A")
# Setter
tissueBoundary(sfe_small, sample_id = "Vis5A") <- tb

Description

Just like annotPred, but performs the operation rather than predicate. For example, this function would return the geometry of the intersections between each Visium spot and the tissue boundary for each sample, rather than whether each Visium spot intersects the tissue boundary. In case one cell/spot gets broken up into multiple geometries, the union of those geometries will be taken, so each cell/spot will only get one geometry.

Usage

annotOp(
  sfe,
  colGeometryName = 1L,
  annotGeometryName = 1L,
  sample_id = "all",
  op = st_intersection
)

Arguments

Value

A sf data frame with geometry column containing the geometries and corresponding column names of sfe as row names. There is no guarantee that the returned geometries are valid or preserve the geometry class (e.g. when the intersection of polygons result into a line of a point).

See Also

annotPred

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
# Get the intersection of myofibers with each Visium spot
myofibers_on_spots <- annotOp(sfe, "spotPoly",
    annotGeometryName = "myofiber_simplified"
)

Description

This function finds binary predicates for the geometry of each cell/spot (i.e. colGeometry) and an annotation geometry for each sample. For example, whether each Visium spot intersects with the tissue boundary in each sample.

Usage

annotPred(
  sfe,
  colGeometryName = 1L,
  annotGeometryName = 1L,
  sample_id = "all",
  pred = st_intersects
)

annotNPred(
  sfe,
  colGeometryName = 1L,
  annotGeometryName = 1L,
  sample_id = "all",
  pred = st_intersects
)

Arguments

Value

For annotPred, a logical vector of the same length as the number of columns in the sample(s) of interest, with barcodes (or corresponding column names of sfe) as names. For annotNPred, a numeric vector of the same length as the number of columns in the sample(s) of interest with barcodes as names, indicating the number of geometries in the annotGeometry of interest returns TRUE for the predicate for each each geometry in the colGeometry of interest.

See Also

annotOp

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
# Whether each spot is in tissue
in_tissue <- annotPred(sfe, "spotPoly", annotGeometryName = "tissueBoundary")
# How many nuclei are there in each Visium spot
n_nuclei <- annotNPred(sfe, "spotPoly", annotGeometryName = "nuclei")

Description

In SFE objects, the annotation geometries don't have to correspond to the dimensions of the gene count matrix, so there generally is no one to one mapping between annotation geometries and cells/spots. However, it may be interesting to relate attributes of annotation geometries to cell/spots so the attributes can be related to gene expression. This function summarizes attributes of an annotGeometry for each cell/spot by a geometric predicate with a colGeometry.

Usage

annotSummary(
  sfe,
  colGeometryName = 1L,
  annotGeometryName = 1L,
  annotColNames = 1L,
  sample_id = "all",
  pred = st_intersects,
  summary_fun = mean
)

Arguments

Value

A data frame whose row names are the relevant column names of sfe, and each column of which is the summary of each column specified in annotColName.

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
s <- annotSummary(sfe, "spotPoly", "myofiber_simplified",
    annotColNames = c("area", "convexity")
)

Description

Get x-y coordinates of the center of any bounding box

Usage

bbox_center(bbox)

Arguments

Value

A numeric vector of length 2.

Examples

bbox <- c(xmin = 0, xmax = 100, ymin = 0, ymax = 80)
bbox_center(bbox)

Description

Find bounding box of the union of all colGeometries and annotGeometries of each sample in the SFE object. This can be used to remove empty space so the tissue and geometries have one corner at the origin so all samples will be on comparable coordinates.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
bbox(sfe, sample_id = "all", include_images = FALSE, include_row = TRUE)

Arguments

Value

For one sample, then a named vector with names xmin, ymin, xmax, and ymax specifying the bounding box. For multiple samples, then a matrix whose columns are samples and whose rows delineate the bounding box.

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
bbox(sfe, sample_id = "Vis5A")

Description

'r lifecycle::badge("experimental")' At present, the BioFormatsImage is designed for OME-TIFF from Xenium and has not been tested on other formats that can be read with BioFormats. The image is not loaded into memory, and when it is, the the BioFormatsImage object is converted into ExtImage because the loaded image is of a class that inherits from Image. The ExtImage class is a thin wrapper inheriting from VirtualSpatialImage so it's compatible with SpatialExperiment from which SFE is derived. This class might drastically change as it matures, say to accommodate other formats supported by BioFormats and to store the transformation matrix rather than loading image into memory upon transform.

Usage

## S4 method for signature 'BioFormatsImage'
show(object)

BioFormatsImage(
  path,
  ext = NULL,
  isFull = TRUE,
  origin = c(0, 0),
  transformation = list()
)

Arguments

Details

Spatial extent is inferred from OME-TIFF metadata if not specified. Physical pixel size from the metadata is used to make the extent in micron space. If physical pixel size is absent from metadata, then the extent will be in pixel space, which might mean that the image will not align with the geometries because often the geometry coordinates are in microns, so a warning is issued in this case.

Affine transformations can be specified in the transformation argument, either by name or by directly specifying the matrix. The transformations specified by name will always preserve the center of the image. When named transformations are chained, name and parameter will be converted to matrix and translation vector the second time a transformation is specified. If the subsequent transformation happens to restore the image to its original place, then transformation specifications will be removed.

Value

A BioFormatsImage object.

See Also

[isFull()], [origin()]

Description

isFULL indicates if the extent is the full extent of the image. origin gets the x-y coordinates of the origin of the image, i.e. the smallest possible x-y coordinate values within the full image.

Usage

## S4 method for signature 'BioFormatsImage'
isFull(x)

## S4 method for signature 'BioFormatsImage'
origin(x)

## S4 method for signature 'BioFormatsImage'
transformation(x)

Arguments

Value

For isFull: Logical scalar indicating whether the extent is the full extent. For origin: Numeric vector of length 2. For transformation, a list.

Description

On top of the cbind method of SpatialExperiment, this method is needed to properly merge the spatialGraphs field in the different SFE objects. rowGeometries and annotGeometries also need to be combined properly.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
cbind(..., deparse.level = 1)

Arguments

Value

A combined SFE object.

Examples

library(SFEData)
sfe_small <- McKellarMuscleData(dataset = "small")
sfe_small2 <- McKellarMuscleData(dataset = "small2")
sfe2 <- cbind(sfe_small, sfe_small2)

Description

Change sample IDs in all fields of the SFE object where sample IDs are present, not just the colData.

Usage

changeSampleIDs(sfe, replacement)

Arguments

Value

An SFE object.

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
sfe <- changeSampleIDs(sfe, c(Vis5A = "sample01"))
sampleIDs(sfe)

Description

Results of spatial analyses on columns in colData, rowData, and geometries are stored in their metadata. The colFeaturedata function allows the users to more directly access these results.

Usage

colFeatureData(sfe)

rowFeatureData(sfe)

geometryFeatureData(sfe, type, MARGIN = 2L)

reducedDimFeatureData(sfe, dimred)

Arguments

Value

A DataFrame.

See Also

getParams

Examples

library(SpatialFeatureExperiment)
library(SingleCellExperiment)
library(SFEData)
library(Voyager)
sfe <- McKellarMuscleData("small")
colGraph(sfe, "visium") <- findVisiumGraph(sfe)
# Moran's I for colData
sfe <- colDataMoransI(sfe, "nCounts")
colFeatureData(sfe)

Description

colGeometries are geometries that correspond to columns of the gene count matrix, such as Visium spots or cells. Same as dimGeometry(x, MARGIN = 2L, ...), with convenience wrappers for getters and setters of special geometries:

spotPoly

Polygons of spots from technologies such as Visium, ST, and slide-seq, which do not correspond to cells. Centroids of the polygons are stored in spatialCoords of the underlying SpatialExperiment object.

ROIPoly

Polygons of regions of interest (ROIs) from technologies such as laser capture microdissection (LCM) and GeoMX DSP. These should correspond to columns of the gene count matrix.

cellSeg

Cell segmentation polygons. If the columns of the gene count matrix are single cells, then this is stored in colGeometries. Otherwise, this is stored in annotGeometries.

nucSeg

Similar to cellSeg, but for nuclei rather than whole cell.

Usage

colGeometry(x, type = 1L, sample_id = 1L, withDimnames = TRUE)

colGeometry(
  x,
  type = 1L,
  sample_id = 1L,
  withDimnames = TRUE,
  translate = TRUE
) <- value

colGeometries(x, withDimnames = TRUE)

colGeometries(x, withDimnames = TRUE, translate = TRUE) <- value

colGeometryNames(x)

colGeometryNames(x) <- value

spotPoly(x, sample_id = 1L, withDimnames = TRUE)

spotPoly(x, sample_id = 1L, withDimnames = TRUE, translate = TRUE) <- value

centroids(x, sample_id = 1L, withDimnames = TRUE)

centroids(x, sample_id = 1L, withDimnames = TRUE, translate = TRUE) <- value

ROIPoly(x, sample_id = 1L, withDimnames = TRUE)

ROIPoly(x, sample_id = 1L, withDimnames = TRUE, translate = TRUE) <- value

cellSeg(x, sample_id = 1L, withDimnames = TRUE)

cellSeg(x, sample_id = 1L, withDimnames = TRUE, translate = TRUE) <- value

nucSeg(x, sample_id = 1L, withDimnames = TRUE)

nucSeg(x, sample_id = 1L, withDimnames = TRUE, translate = TRUE) <- value

Arguments

See Also

[dimGeometries()], [rowGeometries()]

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
cgs <- colGeometries(sfe)
spots <- spotPoly(sfe)

Description

Returns an SFE object whose specified colGeometry returns TRUE with a geometric predicate function (usually intersects) with another geometry of interest. This can be used to subset an SFE object with a tissue boundary or histological region polygon, or crop away empty spaces. After cropping, not only will the cells/spots be subsetted, but also all geometries will be cropped.

Usage

crop(
  x,
  y = NULL,
  colGeometryName = 1L,
  sample_id = "all",
  op = st_intersection,
  keep_whole = "none",
  cover = FALSE
)

Arguments

Details

3D geometries are allowed, but geometric operations can only be performed in x and y but not z.

Value

An SFE object. There is no guarantee that the geometries after cropping are still all valid or preserve the original geometry class.

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
# Subset sfe to only keep spots on tissue
sfe_on_tissue <- crop(sfe, tissueBoundary(sfe),
    colGeometryName = "spotPoly",
    sample_id = "Vis5A"
)

Description

Crop images of class *Image in this package with a bounding box.

Usage

## S4 method for signature 'SpatRasterImage'
cropImg(x, bbox, filename = "")

## S4 method for signature 'BioFormatsImage'
cropImg(x, bbox)

## S4 method for signature 'ExtImage'
cropImg(x, bbox)

Arguments

Value

Image of the same class as input but cropped. For BioFormatsImage, the image is not loaded into memory; only the extent is changed.

See Also

Other image methods: SFE-image, affineImg(), dim,BioFormatsImage-method, ext(), imgRaster(), imgSource(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

While the SpatialFeatureExperiment constructor and *Geometry replacement methods can convert properly formatted ordinary data frames into sf objects which are used to store the geometries internally, the user might want to do the conversion, check if the geometry is valid, and inspect and fix any invalid geometries.

Usage

df2sf(
  df,
  spatialCoordsNames = c("x", "y"),
  spotDiameter = NA,
  geometryType = c("POINT", "LINESTRING", "POLYGON", "MULTIPOINT", "MULTILINESTRING",
    "MULTIPOLYGON"),
  group_col = "group",
  id_col = "ID",
  subid_col = "subID",
  check = TRUE,
  ...
)

Arguments

Value

An sf object.

Examples

# Points, use spotDiameter to convert to circle polygons
# This is done to Visium spots
pts_df <- readRDS(system.file("extdata/pts_df.rds",
    package = "SpatialFeatureExperiment"
))
sf_use <- df2sf(pts_df, geometryType = "POINT", spotDiameter = 0.1)
# Linestring
ls_df <- readRDS(system.file("extdata/ls_df.rds",
    package = "SpatialFeatureExperiment"
))
sf_use <- df2sf(ls_df, geometryType = "LINESTRING")
# Polygon
pol_df <- readRDS(system.file("extdata/pol_df.rds",
    package = "SpatialFeatureExperiment"
))
sf_use <- df2sf(pol_df,
    geometryType = "POLYGON",
    spatialCoordsNames = c("V1", "V2")
)
# Multipolygon
mpol_df <- readRDS(system.file("extdata/mpol_df.rds",
    package = "SpatialFeatureExperiment"
))
sf_use <- df2sf(mpol_df,
    geometryType = "MULTIPOLYGON",
    spatialCoordsNames = c("V1", "V2")
)
# Multiple sample_ids present
multipts_df <- readRDS(system.file("extdata/multipts_df.rds",
    package = "SpatialFeatureExperiment"
))
sf_use <- df2sf(multipts_df, geometryType = "MULTIPOINT")

Description

This is different from other classes. The metadata is read where the dimensions in pixels can be found. The image itself is not read into memory here.

Usage

## S4 method for signature 'BioFormatsImage'
dim(x)

Arguments

Value

An integer vector of length 5 showing the number of rows and columns in the full resolution image. The 5 dimensions are in the order of XYCZT: x, y, channel, z, and time. This is not changed by transformations. Use ext to see the extent after transformation.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), ext(), imgRaster(), imgSource(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

"Dimension geometry" refers to Simple Feature (sf) geometries associated with rows (features, genes) or columns (cells or spots) of the gene count matrix in the SpatialFeatureExperiment object. For each dimension, the number of rows in the sf data frame specifying the geometries must match the size of the dimension of interest. For example, there must be the same number of rows in the sf data frame describing cells as there are cells in the gene count matrix. This page documents getters and setters for the dimension geometries. The getters and setters are implemented in a way similar to those of reducedDims in SingleCellExperiment.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
dimGeometries(x, MARGIN = 2, withDimnames = TRUE)

## S4 replacement method for signature 'SpatialFeatureExperiment'
dimGeometries(x, MARGIN, withDimnames = TRUE, translate = TRUE, ...) <- value

## S4 method for signature 'SpatialFeatureExperiment'
dimGeometryNames(x, MARGIN)

## S4 replacement method for signature 'SpatialFeatureExperiment,numeric,character'
dimGeometryNames(x, MARGIN) <- value

## S4 method for signature 'SpatialFeatureExperiment'
dimGeometry(x, type = 1L, MARGIN, sample_id = 1L, withDimnames = TRUE)

## S4 replacement method for signature 'SpatialFeatureExperiment'
dimGeometry(
  x,
  type = 1L,
  MARGIN,
  sample_id = 1L,
  withDimnames = TRUE,
  translate = TRUE,
  ...
) <- value

Arguments

Value

Getters for multiple geometries return a named list. Getters for names return a character vector of the names. Getters for single geometries return an sf data frame. Setters return an SFE object.

See Also

[colGeometries()], [rowGeometries()]

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")

# Get all column geometries as a named list
# Use MARGIN = 1 or rowGeometry/ies for rowGeometries
cgs <- dimGeometries(sfe, MARGIN = 2)
# Or equivalently
cgs <- colGeometries(sfe)

# Set all column geometries with a named list
dimGeometries(sfe, MARGIN = 2) <- cgs
# Or equivalently
colGeometries(sfe) <- cgs

# Get names of column geometries
cgns <- dimGeometryNames(sfe, MARGIN = 2)
cgns <- colGeometryNames(sfe)

# Set column geometry names
dimGeometryNames(sfe, MARGIN = 2) <- cgns
colGeometryNames(sfe) <- cgns

# Get a specific column geometry by name
spots <- dimGeometry(sfe, "spotPoly", MARGIN = 2)
spots <- colGeometry(sfe, "spotPoly")
# Or equivalently, the wrapper specifically for Visium spot polygons,
# for the name "spotPoly"
spots <- spotPoly(sfe)
# Other colGeometry wrappers for specific names:
# ROIPoly (for LCM and GeoMX DSP), cellSeg and nucSeg (for MERFISH; would
# query annotGeometries for Visium)
# rowGeometry wrappers for specific names: txSpots (MERFISH transcript spots)
# By index
spots <- colGeometry(sfe, 1L)

# Multiple samples, only get geometries for one sample
sfe2 <- McKellarMuscleData("small2")
sfe_combined <- cbind(sfe, sfe2)
spots1 <- colGeometry(sfe, "spotPoly", sample_id = "Vis5A")
spots2 <- spotPoly(sfe_combined, sample_id = "sample02")
# Get geometries for multiple samples
spots3 <- spotPoly(sfe_combined, sample_id = c("Vis5A", "sample02"))
# All samples
spots3 <- spotPoly(sfe_combined, sample_id = "all")

# Set specific column geometry by name
colGeometry(sfe, "foobar") <- spots
# Or use wrapper
spotPoly(sfe) <- spots
# Specify sample_id
colGeometry(sfe_combined, "foobar", sample_id = "Vis5A") <- spots1
# Only entries for the specified sample are set.
foobar <- colGeometry(sfe_combined, "foobar", sample_id = "sample02")

Description

Unlike in SpatialExperiment, images in SFE have extents which are used to align them to the geometries and in geometric operations on SFE objects. These functions get or set the extent for S4 image classes inheriting from VirtualSpatialImage implemented in the SFE package.

Usage

## S4 method for signature 'BioFormatsImage'
ext(x)

## S4 method for signature 'ExtImage'
ext(x)

## S4 method for signature 'SpatRasterImage'
ext(x)

## S4 replacement method for signature 'BioFormatsImage,numeric'
ext(x) <- value

## S4 replacement method for signature 'ExtImage,numeric'
ext(x) <- value

## S4 replacement method for signature 'SpatRasterImage,numeric'
ext(x) <- value

Arguments

Value

Getters return a numeric vector specifying the extent. Setters return a *Image object of the same class as the input.

Note

For SpatRasterImage, the image may be may not be loaded into memory. You can check if the image is loaded into memory with terra::inMemory(imgRaster(x)), and check the original file path with imgSource. If the image is not loaded into memory, then the original file must be present at the path indicated by imgSource in order for any code using the image to work, which includes this function ext.

For BioFormatsImage, internally only the pre-transform extent is stored. The ext getter will apply the transformation on the fly. The setter sets the pre-transformation extent.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), dim,BioFormatsImage-method, imgRaster(), imgSource(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

This is a thin wrapper around the Image class in the EBImage package so it inherits from VirtualSpatialImage to be compatible with SpatialExperiment from which SFE inherits. An ext field is added to specify the spatial extent of the image in microns to facilitate geometric operations on the SFE object (including the images) and plotting with Voyager.

Usage

## S4 method for signature 'ExtImage'
show(object)

ExtImage(img, ext = NULL)

Arguments

Value

An ExtImage object.

Description

This function wraps all spatial neighborhood graphs implemented in the package spdep for the SpatialFeatureExperiment (SFE) class, to find spatial neighborhood graphs for the entities represented by columns or rows of the gene count matrix in the SFE object or spatial entities in the annotGeometries field of the SFE object. Results are stored as listw objects in the spatialGraphs field of the SFE object, as listw is used in many methods that facilitate the spatial neighborhood graph in the spdep, spatialreg, and adespatial. The edge weights of the graph in the listw object are by default style W (see nb2listw) and the unweighted neighbor list is in the neighbours field of the listw object.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
findSpatialNeighbors(
  x,
  sample_id = "all",
  type = "spatialCoords",
  MARGIN = 2,
  method = c("tri2nb", "knearneigh", "dnearneigh", "gabrielneigh", "relativeneigh",
    "soi.graph", "poly2nb"),
  dist_type = c("none", "idw", "exp", "dpd"),
  glist = NULL,
  style = c("raw", "W", "B", "C", "U", "minmax", "S"),
  nn_method = c("bioc", "spdep"),
  alpha = 1,
  dmax = NULL,
  BPPARAM = SerialParam(),
  BNPARAM = KmknnParam(),
  zero.policy = TRUE,
  ...
)

Arguments

Value

For one sample, then a listw object representing the graph, with an attribute "method" recording the function used to build the graph, its arguments, and information about the geometry for which the graph was built. The attribute is used to reconstruct the graphs when the SFE object is subsetted since some nodes in the graph will no longer be present. If sample_id = "all" or has length > 1, then a named list of listw objects, whose names are the sample_ids. To add the list for multiple samples to a SFE object, specify the name argument in the spatialGraphs replacement method, so graph of the same name will be added to the SFE object for each sample.

Note

style = "raw" is only applicable when dist_type is not "none". If dist_type = "none" and style = "raw", then style will default to "W". Using distance based weights does not supplant finding a spatial neighborhood graph. The spatial neighborhood graph is first found and then its edges weighted based on distance in this function.

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
# sample_id is optional when only one sample is present
g <- findSpatialNeighbors(sfe, sample_id = "Vis5A")
attr(g, "method")
# Returns named list for multiple samples
sfe2 <- McKellarMuscleData(dataset = "small2")
sfe_combined <- cbind(sfe, sfe2)
gs <- findSpatialNeighbors(sfe, sample_id = "all")

Description

Visium spots are arranged in a hexagonal grid. This function uses the known locations of the Visium barcodes to construct a neighborhood graph, so adjacent spots are connected by edges. Since the known rows and columns of the spots are used, the unit the spot centroid coordinates are in does not matter.

Usage

findVisiumGraph(x, sample_id = "all", style = "W", zero.policy = NULL)

Arguments

Value

For one sample, then a listw object representing the graph, with an attribute "method" recording the function used to build the graph, its arguments, and information about the geometry for which the graph was built. The attribute is used to reconstruct the graphs when the SFE object is subsetted since some nodes in the graph will no longer be present. If sample_id = "all" or has length > 1, then a named list of listw objects, whose names are the sample_ids. To add the list for multiple samples to a SFE object, specify the name argument in the spatialGraphs replacement method, so graph of the same name will be added to the SFE object for each sample.

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
g <- findVisiumGraph(sfe)
# For multiple samples, returns named list
sfe2 <- McKellarMuscleData(dataset = "small2")
sfe_combined <- cbind(sfe, sfe2)
gs <- findVisiumGraph(sfe, sample_id = "all")

Description

The function 'formatTxSpots' reads the transcript spot coordinates of smFISH-based data and formats the data. The data is not added to an SFE object. If the file specified in 'file_out' already exists, then this file will be read instead of the original file in the 'file' argument, so the processing is not run multiple times. The function 'addTxSpots' adds the data read and processed in 'formatTxSpots' to the SFE object, and reads all transcript spot data. To only read a subset of transcript spot data, first use 'formatTxSpots' to write the re-formatted data to disk. Then read the specific subset and add them separately to the SFE object with the setter functions.

Usage

formatTxSpots(
  file,
  dest = c("rowGeometry", "colGeometry"),
  spatialCoordsNames = c("global_x", "global_y", "global_z"),
  gene_col = "gene",
  cell_col = "cell_id",
  z = "all",
  phred_col = "qv",
  min_phred = 20,
  split_col = NULL,
  not_in_cell_id = c("-1", "UNASSIGNED"),
  z_option = c("3d", "split"),
  flip = FALSE,
  file_out = NULL,
  BPPARAM = SerialParam(),
  return = TRUE
)

addTxSpots(
  sfe,
  file,
  sample_id = 1L,
  spatialCoordsNames = c("global_x", "global_y", "global_z"),
  gene_col = "gene",
  z = "all",
  phred_col = "qv",
  min_phred = 20,
  split_col = NULL,
  z_option = c("3d", "split"),
  flip = FALSE,
  file_out = NULL,
  BPPARAM = SerialParam()
)

Arguments

Value

A sf data frame for vector geometries if 'file_out' is not set. 'SpatRaster' for raster. If there are multiple files written, such as when splitting by cell compartment or when 'dest = "colGeometry"', then a directory with the same name as 'file_out' will be created (but without the extension) and the files are written to that directory with informative names. 'parquet' files that can be read with 'st_read' is written for vector geometries. When 'return = FALSE', the file name or directory (when there're multiple files) is returned.

The 'sf' data frame, or path to file where geometries are written if 'return = FALSE'.

Note

When 'dest = "colGeometry"', the geometries are always written to disk and not returned in memory, because this is essentially the gene count matrix, which is sparse. This kind of reformatting is implemented so users can read in MULTIPOINT geometries with transcript spots for each gene assigned to each cell for spatial point process analyses, where not all genes are loaded at once.

Examples

# Default arguments are for MERFISH
fp <- tempfile()
dir_use <- SFEData::VizgenOutput(file_path = fp)
g <- formatTxSpots(file.path(dir_use, "detected_transcripts.csv"))
unlink(dir_use, recursive = TRUE)

# For CosMX, note the colnames, also dest = "colGeometry"
# Results are written to the tx_spots directory
dir_use <- SFEData::CosMXOutput(file_path = fp)
cg <- formatTxSpots(file.path(dir_use, "Run5642_S3_Quarter_tx_file.csv"),
dest = "colGeometry", z = "all",
cell_col = c("cell_ID", "fov"),
gene_col = "target", not_in_cell_id = "0",
spatialCoordsNames = c("x_global_px", "y_global_px", "z"),
file_out = file.path(dir_use, "tx_spots"))
# Cleanup
unlink(dir_use, recursive = TRUE)

Description

To preset parameters such as spatialCoordsNames, gene_col, cell_col, and phred_col that are standard for the output of the technology.

Usage

formatTxTech(
  data_dir,
  tech = c("Vizgen", "Xenium", "CosMX"),
  dest = c("rowGeometry", "colGeometry"),
  z = "all",
  min_phred = 20,
  split_cell_comps = FALSE,
  z_option = c("3d", "split"),
  flip = FALSE,
  file_out = NULL,
  BPPARAM = SerialParam(),
  return = TRUE
)

addTxTech(
  sfe,
  data_dir,
  sample_id = 1L,
  tech = c("Vizgen", "Xenium", "CosMX"),
  z = "all",
  min_phred = 20,
  split_cell_comps = FALSE,
  z_option = c("3d", "split"),
  flip = FALSE,
  file_out = NULL,
  BPPARAM = SerialParam()
)

Arguments

Value

The 'sf' data frame, or path to file where geometries are written if 'return = FALSE'.

Examples

library(SFEData)
fp <- tempfile()
dir_use <- XeniumOutput("v2", file_path = fp)
fn_tx <- formatTxTech(dir_use, tech = "Xenium", flip = TRUE, return = FALSE,
                      file_out = file.path(dir_use, "tx_spots.parquet"))

Description

The GeoParquet files for geometries are typically written and read with the sfarrow package, but to add only a select few genes to the SFE object say for visualization purposes, the Parquet GDAL driver is required in order to use GDAL's SQL to query the GeoParquet file to only load the few genes requested. The transcript spots from a large dataset can take up a lot of memory if all loaded.

Usage

gdalParquetAvailable()

Details

The Parquet driver has been supported since GDAL 3.5.0. The arrow C++ library must be installed in order to make the Parquet driver available. When arrow is installed, newer versions of GDAL installed from Homebrew (Mac) should have the Parquet driver. For Linux, the binary from apt-get's default repo is 3.4.1 (as of April 2024). To use the Parquet driver, GDAL may need to be installed from source. See script from the geospatial rocker. A Voyager docker container with the Parquet driver will soon be provided.

Value

Logical, indicating whether the Parquet driver is present.

Examples

gdalParquetAvailable()

Description

The getParams function allows users to access the parameters used to compute the results that may be stored in colFeatureData.

Usage

getParams(
  sfe,
  name,
  local = FALSE,
  colData = FALSE,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  reducedDimName = NULL
)

Arguments

Value

A named list showing the parameters

Examples

library(SFEData)
library(scater)
library(Voyager)
sfe <- McKellarMuscleData("small")
colGraph(sfe, "visium") <- findVisiumGraph(sfe)
sfe <- colDataMoransI(sfe, "nCounts")
getParams(sfe, "moran", colData = TRUE)

Description

This function gets physical size of pixels in each resolution of a OME-TIFF pyramid in BioFormatsImage.

Usage

getPixelSize(file, resolution = 1L)

Arguments

Value

Numeric vector of length 2 of pixel size in x and y. Usually they're the same.

Examples

library(SFEData)
fp <- tempfile()
dir_use <- XeniumOutput("v1", file_path = fp)
# RBioFormats null pointer error
try(getPixelSize(file.path(dir_use, "morphology_focus.ome.tif")))
getPixelSize(file.path(dir_use, "morphology_focus.ome.tif"))
unlink(dir_use, recursive = TRUE)

Description

Get column names for x, y, and z coordinates, gene IDs, and cell IDs from the transcript file and get file paths for transcript spot coordinates given technology.

Usage

getTechTxFields(tech, data_dir = NULL)

Arguments

Value

A named list with elements:

spatialCoordsNames

A character vector for column names for the xyz coordinates of the transcript spots.

gene_col

Column name for gene IDs.

cell_col

Column name for cell IDs.

fn

File path of the transcript spot file.

Description

The title is self-explanatory. Some functions require image_id to get or set images.

Usage

imageIDs(sfe)

Arguments

Value

A character vector of image_ids.

Examples

fp <- system.file(file.path("extdata", "sample01"),
package = "SpatialFeatureExperiment")
sfe <- read10xVisiumSFE(fp, type = "sparse")
imageIDs(sfe)

Description

Modify or replace images stored in a SpatialExperiment object. This is different from addImg which adds the image from files and can't replace existing images, which is there to be consistent with SpatialExperiment. This setter here can replace existing images with another object that inherits from VirtualSpatialImage, including SpatRasterImage, BioFormatsImage, and ExtImage.

Usage

## S4 replacement method for signature 'SpatialExperiment'
Img(x, sample_id = 1L, image_id, scale_fct = 1) <- value

Arguments

Value

SFE object with the new image added.

Examples

library(EBImage)
library(SFEData)
library(RBioFormats)
fp <- tempfile()
fn <- XeniumOutput("v2", file_path = fp)
# Weirdly the first time I get the null pointer error
try(sfe <- readXenium(fn))
sfe <- readXenium(fn)
img <- getImg(sfe) |> toExtImage(resolution = 1L)
img <- img[,,1] > 500
Img(sfe, image_id = "mask") <- img
imageIDs(sfe)
unlink(fn, recursive = TRUE)

Description

In SFE, S4 classes inheriting from VirtualSpatialImage have been implemented to make these image classes compatible with SpatialExperiment. The imgRaster methods in SFE are meant to extract the original image from the *Image classes, such as SpatRaster from SpatRasterImage, and Image from ExtImage and BioFormatsImage. For BioFormatsImage, the image of the specified resolution will be read into memory as AnnotatedImage, which inherits from EBImage::Image.

Arguments

Value

SpatRaster from SpatRasterImage, and Image from ExtImage and BioFormatsImage. For BioFormatsImage, the image of the specified resolution will be read into memory as AnnotatedImage and ExtImage, which both inherit from EBImage::Image.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), dim,BioFormatsImage-method, ext(), imgSource(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

Get the file path of images that are on disk and not read into memory. Only applies to SpatRasterImage and BioFormatsImage.

Usage

## S4 method for signature 'SpatRasterImage'
imgSource(x)

## S4 method for signature 'BioFormatsImage'
imgSource(x)

## S4 method for signature 'ExtImage'
imgSource(x)

Arguments

Value

String, file path to the original image on disk. For SpatRasterImage, if the image is loaded into memory, then NULL.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), dim,BioFormatsImage-method, ext(), imgRaster(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

Edge weights are used in the adjacency matrix. Because most elements of the matrix are 0, using sparse matrix greatly reduces memory use.

Usage

listw2sparse(listw)

Arguments

Value

A sparse dgCMatrix, whose row represents each cell or spot and whose columns represent the neighbors. The matrix does not have to be symmetric. If region.id is present in the listw object, then it will be the row and column names of the output matrix.

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
g <- findVisiumGraph(sfe)
mat <- listw2sparse(g)

Description

Local spatial statics like local Moran's I, local Geary's C, Getis-Ord Gi*, and geographically weighted summary statistics return values at each spatial location. Just like dimension reductions, these results are clearly associated with the broader SFE object, so they should have a place within the object. However, a separate field is needed because these analyses are conceptually distinct from dimension reduction. Also, each feature (e.g. gene) can have its own results with values at each location. The localResults field in the SFE object stores these results that has a value for each spatial location.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
localResults(
  x,
  sample_id = "all",
  name = "all",
  features = NULL,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  withDimnames = TRUE,
  swap_rownames = NULL,
  ...
)

## S4 replacement method for signature 'SpatialFeatureExperiment'
localResults(
  x,
  sample_id = "all",
  name = "all",
  features = NULL,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  withDimnames = TRUE,
  swap_rownames = NULL,
  ...
) <- value

## S4 method for signature 'SpatialFeatureExperiment'
localResultNames(x)

## S4 replacement method for signature 'SpatialFeatureExperiment,character'
localResultNames(x) <- value

## S4 method for signature 'SpatialFeatureExperiment'
localResultFeatures(
  x,
  type = 1L,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  swap_rownames = NULL
)

## S4 method for signature 'SpatialFeatureExperiment'
localResultAttrs(
  x,
  type = 1L,
  feature,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  swap_rownames = NULL
)

## S4 method for signature 'SpatialFeatureExperiment'
localResult(
  x,
  type = 1L,
  feature,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  sample_id = 1L,
  withDimnames = TRUE,
  simplify = TRUE,
  swap_rownames = NULL
)

## S4 replacement method for signature 'SpatialFeatureExperiment'
localResult(
  x,
  type = 1L,
  feature,
  colGeometryName = NULL,
  annotGeometryName = NULL,
  sample_id = 1L,
  withDimnames = TRUE
) <- value

Arguments

Value

localResults returns a named list each element of which is a set of local results of interest. localResult returns a matrix or a data frame, whichever the original is when it's set. localResultNames returns a character vector. Setters return an SFE object with the desired field set. For genes and colData columns, the local results are stored in the localResults field in int_colData, whereas for colGeometries and annotGeometries, the local results are stored as columns in the same sf data frames. localResultFeatures returns a character vector of names of features for which local results are available. localResultAttrs returns a character vector of the column names of the local results of one type for one feature. It returns NULL if the results are a vector.

Examples

# Toy example
sfe <- readRDS(system.file("extdata/sfe_toy.rds",
    package = "SpatialFeatureExperiment"
))
# localResults functions are written for organizing results from local
# spatial statistics (see the Voyager package). But for the examples here,
# random toy matrices are used. The real results are often matrices, with a
# matrix for each feature.
library(S4Vectors)
set.seed(29)
toy_res1 <- matrix(rnorm(10),
    nrow = 5, ncol = 2,
    dimnames = list(colnames(sfe), c("meow", "purr"))
)
toy_res1b <- matrix(rgamma(10, shape = 2),
    nrow = 5, ncol = 2,
    dimnames = list(colnames(sfe), c("meow", "purr"))
)
toy_df1 <- DataFrame(gene1 = I(toy_res1), gene2 = I(toy_res1b))

toy_res2 <- matrix(rpois(10, lambda = 2),
    nrow = 5, ncol = 2,
    dimnames = list(colnames(sfe), c("sassy", "tortitude"))
)
toy_df2 <- DataFrame(gene1 = I(toy_res2))
# Set all local results
localResults(sfe) <- list(localmoran = toy_df1, Gistar = toy_df2)
# Get all local results
lrs <- localResults(sfe)

# Set results of the same type for multiple genes
localResults(sfe, name = "localmoran") <- toy_df1
# Can also use a list
localResults(sfe, name = "localmoran") <- as.list(toy_df1)
# Get results of the same type for multiple genes
lrs <- localResults(sfe, name = "localmoran", features = c("gene1", "gene2"))

# Set results for one type and one gene
localResult(sfe, "localmoran", feature = "gene1") <- toy_res1
# Get results for one type and one gene
lr <- localResult(sfe, "localmoran", feature = "gene1")

# Set results for a feature in colGeometries
cg_toy <- readRDS(system.file("extdata/cg_toy.rds",
    package = "SpatialFeatureExperiment"
))
colGeometry(sfe, "cg") <- cg_toy
localResult(sfe, "localmoran",
    feature = "gene1",
    colGeometryName = "cg"
) <- toy_res1
# Get results for a feature in colGeometries
lr <- localResult(sfe, "localmoran", "gene1", colGeometryName = "cg")

Description

Flip images along the middle horizontal or vertical axis.

Usage

## S4 method for signature 'SpatRasterImage'
mirrorImg(
  x,
  direction = c("vertical", "horizontal"),
  filename = "",
  maxcell = NULL,
  ...
)

## S4 method for signature 'BioFormatsImage'
mirrorImg(x, direction = c("vertical", "horizontal"), ...)

## S4 method for signature 'ExtImage'
mirrorImg(x, direction = c("vertical", "horizontal"), ...)

Arguments

Value

*Image object of the same class.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), dim,BioFormatsImage-method, ext(), imgRaster(), imgSource(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Description

Each sample in the SFE object has a separate spatial neighborhood graph. Spatial analyses performed jointly on multiple samples require a combined spatial neighborhood graph from the different samples, where the different samples would be disconnected components of the graph. This combined adjacency matrix can be used in MULTISPATI PCA.

Usage

multi_listw2sparse(listws)

Arguments

Value

A sparse dgCMatrix of the combined spatial neighborhood graph, with the original spatial neighborhood graphs of the samples on the diagonal. When the input is an SFE object, the rows and columns will match the column names of the SFE object.

Examples

# example code

Description

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

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])
list.files(file.path(samples[1], "spatial"))
(sfe <- read10xVisiumSFE(samples, sample_id = sample_ids,
    type = "sparse", data = "filtered",
    load = FALSE
))

# 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.
                 )

Description

This function reads the standard CosMX output into an SFE object, as in "Basic Data Files" on the Nanostring website.

Usage

readCosMX(
  data_dir,
  z = "all",
  sample_id = "sample01",
  add_molecules = FALSE,
  split_cell_comps = FALSE,
  BPPARAM = SerialParam(),
  file_out = file.path(data_dir, "tx_spots.parquet"),
  z_option = c("3d", "split")
)

Arguments

Value

An SFE object. Cell polygons are written to 'cell_boundaries_sf.parquet' in 'data_dir'. If reading transcript spots ('add_molecules = TRUE'), then the reformatted transcript spots are saved to file specified in the 'file_out' argument, which is by default 'tx_spots.parquet' in the same directory as the rest of the data.

Examples

fp <- tempfile()
dir_use <- SFEData::CosMXOutput(file_path = fp)
sfe <- readCosMX(dir_use, z = "all", add_molecules = TRUE)
# Clean up
unlink(dir_use, recursive = TRUE)

Description

I speculate that in practice, the most common use of the transcript spots is visualization, and only a few genes can be visualized at a time or the spots will overcrowd. Then it doesn't make sense to load the transcript spots of all genes into memory as they can take up a lot of memory. The function readSelectTx reads transcript spots of select genes into R, and the function addSelectTx adds them to rowGeometries of the SFE object.

Usage

readSelectTx(file, gene_select, z = "all", z_option = c("3d", "split"))

addSelectTx(
  sfe,
  file,
  gene_select,
  sample_id = 1L,
  z = "all",
  z_option = c("3d", "split"),
  swap_rownames = NULL
)

Arguments

Value

When there are multipel parquet files to be read, a list of sf data frames with MULTIPOINT geometry for genes selected. When there is only one file, then one sf data frame. For addSelectTx, an SFE object with the transcript spots of the selected genes added.

Note

The GDAL Parquet driver is required for this function, though not for other functions that work with GeoParquet files. GDAL Parquet driver has been supported since GDAL 3.5.0, but is not part of the default installation. The z and z_option arguments are there since the file names contain z-plane information when relevant. See the GDAL documentation page for the Parquet driver.

Examples

library(SFEData)
if (gdalParquetAvailable()) {
    fp <- tempfile()
    dir_use <- XeniumOutput("v2", file_path = fp)
    fn_tx <- formatTxTech(dir_use, tech = "Xenium", flip = TRUE, return = FALSE,
                          file_out = file.path(dir_use, "tx_spots.parquet"))
    gene_select <- c("ACE2", "BMX")
    df <- readSelectTx(fn_tx, gene_select)
    # RBioFormats null pointer error the first time
    try(sfe <- readXenium(dir_use))
    sfe <- readXenium(dir_use)
    sfe <- addSelectTx(sfe, fn_tx, head(rownames(sfe), 5), swap_rownames = "Symbol")
    unlink(dir_use, recursive = TRUE)
}

Description

This function reads the standard Vizgen MERFISH output into an SFE object. The coordinates are in microns. Cell centroids are read into colGeometry "centroids", and cell segmentations are read into colGeometry "cellSeg". The image(s) (polyT, DAPI, and cell boundaries) are also read as SpatRaster objects so they are not loaded into memory unless necessary. Because the image's origin is the top left while the geometry's origin is bottom left, either the image or the geometry needs to be flipped. Because the image accompanying MERFISH datasets are usually very large, the coordinates will be flipped so the flipping operation won't load the entire image into memory. Large datasets with hundreds of thousands of cells can take a while to read if reading transcript spots as it takes a while to convert the spots to MULTIPOINT geometries.

Usage

readVizgen(
  data_dir,
  z = "all",
  sample_id = "sample01",
  min_area = 15,
  image = c("DAPI", "PolyT", "Cellbound"),
  flip = c("geometry", "image", "none"),
  max_flip = "50 MB",
  filter_counts = FALSE,
  add_molecules = FALSE,
  use_bboxes = FALSE,
  use_cellpose = TRUE,
  BPPARAM = SerialParam(),
  file_out = file.path(data_dir, "detected_transcripts.parquet"),
  z_option = c("3d", "split")
)

Arguments

Value

A SpatialFeatureExperiment object.

Note

Since the transcript spots file is often very large, we recommend only using add_molecules = TRUE on servers with a lot of memory. If reading all z-planes, conversion of transcript spot geometry to parquet file might fail due to arrow data length limit. In a future version, when the transcript spot geometry is large, it will be written to multiple separate parquet files which are then concatenated with DuckDB. Also, in a future version, the transcript spot processing function might be rewritten in C++ to stream the original CSV file so it's not entirely loaded into memory.

Examples

fp <- tempfile()
dir_use <- SFEData::VizgenOutput(file_path = fp)
sfe <- readVizgen(dir_use, z = 3L, image = "PolyT",
flip = "geometry")

## Filtering of counts, and addition of molecule coordinates..
sfe <- readVizgen(dir_use, z = 3L, image = "PolyT", filter_counts = TRUE,
add_molecules = TRUE, flip = "geometry")

unlink(dir_use, recursive = TRUE)

Description

This function reads the standard 10X Xenium output into an SFE object.

Usage

readXenium(
  data_dir,
  sample_id = "sample01",
  image = c("morphology_focus", "morphology_mip"),
  segmentations = c("cell", "nucleus"),
  row.names = c("id", "symbol"),
  flip = c("geometry", "image", "none"),
  max_flip = "50 MB",
  filter_counts = FALSE,
  add_molecules = FALSE,
  min_phred = 20,
  BPPARAM = SerialParam(),
  file_out = file.path(data_dir, "tx_spots.parquet")
)

Arguments

Value

An SFE object. If reading segmentations, the cell or nuclei segmentation will be saved to 'cell_boundaries_sf.parquet' and 'nucleus_boundaries_sf.parquet' respectively in 'data.dir' so next time the boundaries can be read much more quickly. If reading transcript spots ('add_molecules = TRUE'), then the reformatted transcript spots are saved to file specified in the 'file_out' argument, which is by default 'tx_spots.parquet' in the same directory as the rest of the data. If images are present, then the images will be of the BioFormatsImage class and not loaded into memory until necessary in later operations.

Note

Sometimes when reading images, you will see this error the first time: 'java.lang.NullPointerException: Cannot invoke "loci.formats.DimensionSwapper.setMetadataFiltered(boolean)" because "RBioFormats.reader" is null'. See this issue https://github.com/aoles/RBioFormats/issues/42 Rerun the code and it should work the second time.

Examples

library(SFEData)
library(RBioFormats)
fp <- tempfile()
dir_use <- XeniumOutput("v2", file_path = fp)
# RBioFormats issue
try(sfe <- readXenium(dir_use, add_molecules = TRUE))
sfe <- readXenium(dir_use, add_molecules = TRUE)
unlink(dir_use, recursive = TRUE)

Description

These are some commonly used getters and setters of classes that SFE inherits so you don't have to separately attach those packages to use these functions.

Usage

colData(x, ...)

rowData(x, use.names = TRUE, ...)

colData(x, ...) <- value

spatialCoords(x, ...)

spatialCoords(x) <- value

spatialCoordsNames(x)

getImg(x, ...)

imgData(x)

rmvImg(x, ...)

counts(object, ...)

logcounts(object, ...)

reducedDim(x, type, ...)

Arguments

Description

For each sample independently, all geometries and spatialCoords are translated so the origin is at the minimum coordinates of the bounding box of all geometries of the sample. This way coordinates of different samples will be more comparable. This removes empty space in the images if present.

Usage

removeEmptySpace(sfe, sample_id = "all")

Arguments

Value

An SFE object with empty space removed.

Note

Unlike other functions in this package, this function operates on all samples by default.

Examples

library(SFEData)
library(SingleCellExperiment)
sfe <- McKellarMuscleData("full")
# Only keep spots on tissue
sfe <- sfe[, colData(sfe)$in_tissue]
# Move the coordinates of the tissue
sfe <- removeEmptySpace(sfe)

Description

As in SpatialExperiment, rotation here must be a multiple of 90 degrees.

Usage

## S4 method for signature 'SpatRasterImage'
rotateImg(x, degrees, maxcell = 1e+07, ...)

## S4 method for signature 'BioFormatsImage'
rotateImg(x, degrees, ...)

## S4 method for signature 'ExtImage'
rotateImg(x, degrees, ...)

Arguments

Value

SpatRasterImage will be loaded into memory and converted to ExtImage. Otherwise *Image object of the same class.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), dim,BioFormatsImage-method, ext(), imgRaster(), imgSource(), mirrorImg(), scaleImg(), translateImg(), transposeImg()

Description

rowGeometries are geometries that corresponding to rows of the gene count matrix, such as smFISH transcript spots. The txSpots() function is a convenience wrapper for transcript spots, although this entirely depends on the rowGeometry being named txSpots.

Usage

rowGeometry(x, type = 1L, sample_id = 1L, withDimnames = TRUE)

rowGeometry(
  x,
  type = 1L,
  sample_id = 1L,
  withDimnames = TRUE,
  partial = FALSE,
  translate = TRUE
) <- value

rowGeometries(x, sample_id = "all", withDimnames = TRUE)

rowGeometries(
  x,
  sample_id = "all",
  withDimnames = TRUE,
  partial = FALSE,
  translate = TRUE
) <- value

rowGeometryNames(x)

rowGeometryNames(x) <- value

txSpots(x, sample_id = 1L, withDimnames = TRUE)

txSpots(
  x,
  sample_id = 1L,
  withDimnames = TRUE,
  partial = FALSE,
  translate = TRUE
) <- value

Arguments

Details

When there are multiple samples in the SFE object, rowGeometries for each sample has the sample_id appended to the name of the geometry. For example, if the name is txSpots and the sample ID is sample01, then the actual name of the rowGeometry is txSpots_sample01. In the getter, one can still specify rowGeometry(sfe, "txSpots", sample_id = "sample01").

Appending the sample_id is unnecessary when there is only one sample, but sample_id will be appended when to SFE objects are combined with cbind. It is necessary to distinguish bewteen different samples because they can have overlapping coordinate values.

See Also

[dimGeometries()], [colGeometries()]

Examples

library(SFEData)
library(RBioFormats)
fp <- tempfile()
dir_use <- XeniumOutput("v2", file_path = fp)
# RBioFormats issue
try(sfe <- readXenium(dir_use, add_molecules = TRUE))
sfe <- readXenium(dir_use, add_molecules = TRUE)
rowGeometries(sfe)
rowGeometryNames(sfe)
tx <- rowGeometry(sfe, "txSpots")
txSpots(sfe)
unlink(dir_use, recursive = TRUE)

Description

The title is self-explanatory.

Usage

sampleIDs(sfe)

Arguments

Value

A character vector of all unique entries of the sample_id column in colData(x).

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
sampleIDs(sfe)

Description

Saving SFE objects as RDS files is complicated by the SpatRaster class of the images. If present, the images need to be wrapped with the wrap function in terra before serializing the SFE object. Otherwise the images will be invalid pointers when the RDS is reloaded. If the image does not fit in memory and its file source is unknown, then it will be written to a temporary file, which is reloaded when the RDS file is loaded. When an SFE object with images is read from an RDS file, the images will not be unwrapped until necessary.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
saveRDS(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL
)

Arguments

Value

Invisibly NULL.

Examples

outdir <- system.file("extdata", package = "SpatialFeatureExperiment")
samples <- file.path(outdir, paste0("sample0", 1:2))
sfe <- read10xVisiumSFE(samples, type = "sparse", data = "filtered")
saveRDS(sfe, "foo.rds")
# Clean up
file.remove("foo.rds")

Description

This function scales the image about its center. After scaling, the center of the image is not shifted.

Usage

## S4 method for signature 'AlignedSpatialImage'
scaleImg(x, factor, ...)

Arguments

Value

A *Image object of the same class that has been scaled. Behind the scene, it's only the extent that has been changed and the images are not changed. The center of the image is unchanged.

See Also

Other image methods: SFE-image, affineImg(), cropImg(), dim,BioFormatsImage-method, ext(), imgRaster(), imgSource(), mirrorImg(), rotateImg(), translateImg(), transposeImg()

Description

Generics of these functions are defined in SpatialExperiment, except for transposeImg. These SFE methods cater to the new image-related classes in SFE. The SPE method for getImg, rmvImg, and imgRaster don't need to be modified for SFE and are hence not implemented here, but are simply re-exported.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
addImg(x, imageSource, sample_id = 1L, image_id, extent = NULL, scale_fct = 1)

## S4 method for signature 'SpatialFeatureExperiment'
transposeImg(
  x,
  sample_id = 1L,
  image_id = NULL,
  maxcell = 1e+07,
  filename = ""
)

## S4 method for signature 'SpatialFeatureExperiment'
mirrorImg(
  x,
  sample_id = 1L,
  image_id = NULL,
  direction = "vertical",
  maxcell = 1e+07,
  filename = ""
)

## S4 method for signature 'SpatialFeatureExperiment'
rotateImg(x, sample_id = 1L, image_id = NULL, degrees, maxcell = 1e+07)

## S4 method for signature 'SpatialFeatureExperiment'
translateImg(x, sample_id = 1L, image_id = NULL, v)

## S4 method for signature 'SpatialFeatureExperiment'
scaleImg(x, sample_id = 1L, image_id = NULL, factor)

## S4 method for signature 'SpatialFeatureExperiment'
affineImg(x, sample_id = 1L, image_id = NULL, M, v)

Arguments

Details

Method of transposeImg, mirrorImg, and rotateImg perform the method on all images within the SFE object that are specified with sample_id and image_id. For images that are not loaded into memory, rotateImg will load SpatRasterImage into memory and all image operations except translate will load BioFormatsImage into memory.

Note

If the image is already a GeoTIFF file that already has an extent, then the extent associated with the file will be honored and the extent and scale_fct arguments are ignored. Transposing the image is just like transposing a matrix. It's flipped about the line going from the top left to the bottom right.

See Also

Other image methods: affineImg(), cropImg(), dim,BioFormatsImage-method, ext(), imgRaster(), imgSource(), mirrorImg(), rotateImg(), scaleImg(), translateImg(), transposeImg()

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
img_path <- system.file(file.path("extdata", "sample01", "outs", "spatial",
"tissue_lowres_image.png"), package = "SpatialFeatureExperiment")
sfe <- addImg(sfe, img_path, sample_id = "Vis5A", image_id = "lowres", scale_fct =
0.023)
img <- getImg(sfe)
# SpatRasterImage method
img_t <- transposeImg(img)
# SFE method
sfe <- transposeImg(sfe, sample_id = "Vis5A", image_id = "lowres")

Description

These functions perform affine transformations on SFE objects, including all geometries and images. The transformation is performed on each sample as a whole. This differs from functions such as mirrorImg in that mirrorImg and rotateImg transform the image with the center at the center of the image itself. In contrast, the center of transformation here is the center of the bounding box of the entire sample, including images.

Usage

transpose(sfe, sample_id = "all", maxcell = NULL, filename = "")

mirror(
  sfe,
  sample_id = "all",
  direction = c("vertical", "horizontal"),
  maxcell = NULL,
  filename = ""
)

rotate(sfe, sample_id = "all", degrees, maxcell = 1e+07)

translate(sfe, sample_id = "all", v)

scale(sfe, sample_id = "all", factor)

affine(sfe, sample_id = "all", M, v, maxcell = 1e+07)

Arguments

Details

For images that are not loaded into memory, rotateImg will load SpatRasterImage into memory and all image operations except translate will load BioFormatsImage into memory.

Value

An SFE object with the sample(s) transformed.

Examples

library(SFEData)
sfe <- McKellarMuscleData("small")
sfe2 <- transpose(sfe)
sfe3 <- mirror(sfe)

Description

Printing summaries of colGeometries, rowGeometries, and annotGeometries in addition to what's shown for SpatialExperiment. Geometry names and types are printed.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
show(object)

Arguments

Value

None (invisible NULL).

Examples

library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
sfe # The show method is implicitly called

Description

Create a SpatialFeatureExperiment object.

Usage

SpatialFeatureExperiment(
  assays,
  colData = DataFrame(),
  rowData = NULL,
  sample_id = "sample01",
  spatialCoordsNames = c("x", "y"),
  spatialCoords = NULL,
  colGeometries = NULL,
  rowGeometries = NULL,
  annotGeometries = NULL,
  spotDiameter = NA_real_,
  annotGeometryType = "POLYGON",
  spatialGraphs = NULL,
  unit = c("full_res_image_pixel", "micron"),
  ...
)

Arguments

Value

A SFE object. If neither colGeometries nor spotDiameter is specified, then a colGeometry called "centroids" will be made, which is essentially the spatial coordinates as sf POINTs. If spotDiameter is specified, but not colGeometries, then the spatial coordinates will be buffered by half the diameter to get spots with the desired diameter, and the resulting colGeometry will be called "spotPoly", for which there's a convenience getter and setter, spotPoly.

Examples

library(Matrix)
data("visium_row_col")
coords1 <- visium_row_col[visium_row_col$col < 6 & visium_row_col$row < 6, ]
coords1$row <- coords1$row * sqrt(3)
cg <- df2sf(coords1[, c("col", "row")], c("col", "row"), spotDiameter = 0.7)

set.seed(29)
col_inds <- sample(seq_len(13), 13)
row_inds <- sample(seq_len(5), 13, replace = TRUE)
values <- sample(seq_len(5), 13, replace = TRUE)
mat <- sparseMatrix(i = row_inds, j = col_inds, x = values)
colnames(mat) <- coords1$barcode
rownames(mat) <- sample(LETTERS, 5)
rownames(cg) <- colnames(mat)

sfe <- SpatialFeatureExperiment(list(counts = mat),
    colData = coords1,
    spatialCoordsNames = c("col", "row"),
    spotDiameter = 0.7
)
sfe2 <- SpatialFeatureExperiment(list(counts = mat),
    colGeometries = list(foo = cg)
)

Description

This class inherits from the SpatialExperiment (SPE) class, which in turn inherits from SingleCellExperiment (SCE). SpatialFeatureExperiment stores geometries of spots or cells in sf objects which form columns of a DataFrame which is in turn a column of the int_colData DataFrame of the underlying SCE object, just like reducedDim in SCE. Geometries of the tissue outline, pathologist annotations, and objects (e.g. nuclei segmentation in a Visium dataset) are stored in sf objects in a named list called annotGeometries in int_metadata.

Description

The SpatialFeatureExperiment class inherits from SpatialExperiment, which in turn inherits from SingleCellExperiment. A SpatialExperiment object with geometries in colGeometries in the int_colData, rowGeometries in the int_elementMetadata, or annotGeometries in the int_metadata can be directly converted to SpatialFeatureExperiment with as(spe, "SpatialFeatureExperiment"). A SpatialExperiment object without the geometries can also be converted; the coordinates in the spatialCoords field will be used to make POINT geometries named "centroids" to add to colGeometries. The geometries can also be supplied separately when using toSpatialFeatureExperiment. Images are converted to SpatRaster.

Usage

## S4 method for signature 'SpatialExperiment'
toSpatialFeatureExperiment(
  x,
  colGeometries = NULL,
  rowGeometries = NULL,
  annotGeometries = NULL,
  spatialCoordsNames = c("x", "y"),
  annotGeometryType = "POLYGON",
  spatialGraphs = NULL,
  spotDiameter = NA,
  unit = NULL
)

## S4 method for signature 'SingleCellExperiment'
toSpatialFeatureExperiment(
  x,
  sample_id = "sample01",
  spatialCoordsNames = c("x", "y"),
  spatialCoords = NULL,
  colGeometries = NULL,
  rowGeometries = NULL,
  annotGeometries = NULL,
  annotGeometryType = "POLYGON",
  spatialGraphs = NULL,
  spotDiameter = NA,
  scaleFactors = 1,
  imageSources = NULL,
  image_id = NULL,
  loadImage = TRUE,
  imgData = NULL,
  unit = NULL
)

## S4 method for signature 'Seurat'
toSpatialFeatureExperiment(
  x,
  add_molecules = TRUE,
  flip = c("geometry", "image", "none"),
  image_scalefactors = c("lowres", "hires"),
  unit = NULL,
  BPPARAM = SerialParam()
)

Arguments

Value

A SpatialFeatureExperiment object

Examples

library(SpatialExperiment)
example(read10xVisium)
# There can't be duplicate barcodes
colnames(spe) <- make.unique(colnames(spe), sep = "-")
rownames(spatialCoords(spe)) <- colnames(spe)
sfe <- toSpatialFeatureExperiment(spe)
# For coercing Seurat to SFE see this -> ./vignettes/seurat_sfe_coerce.Rmd

Description

The method for SFE reconstructs the spatial graphs when the SFE object is subsetted as the listw objects encodes the nodes with indices which are no longer valid after subsetting as some nodes are no longer present.

Usage

## S4 method for signature 'SpatialFeatureExperiment,ANY,ANY,ANY'
x[i, j, ..., drop = FALSE]

Arguments

Value

A subsetted SpatialFeatureExperiment object.

Examples

# Just like subsetting matrices and SingleCellExperiment
library(SFEData)
sfe <- McKellarMuscleData(dataset = "small")
sfe_subset <- sfe[seq_len(10), seq_len(10), drop = TRUE]
# Gives warning as graph reconstruction fails

sfe_subset <- sfe[seq_len(10), seq_len(10)]

Description

Spatial neighborhood graphs as spdep's listw objects are stored in the int_metadata of the SFE object. The listw class is used because spdep has many useful methods that rely on the neighborhood graph as listw.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
spatialGraphs(x, MARGIN = NULL, sample_id = "all", name = "all")

colGraphs(x, sample_id = "all", name = "all")

rowGraphs(x, sample_id = "all", name = "all")

annotGraphs(x, sample_id = "all", name = "all")

## S4 replacement method for signature 'SpatialFeatureExperiment'
spatialGraphs(x, MARGIN = NULL, sample_id = "all", name = "all") <- value

colGraphs(x, sample_id = "all", name = "all") <- value

rowGraphs(x, sample_id = "all", name = "all") <- value

annotGraphs(x, sample_id = "all", name = "all") <- value

## S4 method for signature 'SpatialFeatureExperiment,numeric'
spatialGraphNames(x, MARGIN, sample_id = 1L)

## S4 replacement method for signature 'SpatialFeatureExperiment,numeric,ANY,character'
spatialGraphNames(x, MARGIN, sample_id = 1L) <- value

colGraphNames(x, sample_id = 1L)

rowGraphNames(x, sample_id = 1L)

annotGraphNames(x, sample_id = 1L)

colGraphNames(x, sample_id = 1L) <- value

rowGraphNames(x, sample_id = 1L) <- value

annotGraphNames(x, sample_id = 1L) <- value

## S4 method for signature 'SpatialFeatureExperiment'
spatialGraph(x, type = 1L, MARGIN, sample_id = 1L)

colGraph(x, type = 1L, sample_id = 1L)

rowGraph(x, type = 1L, sample_id = 1L)

annotGraph(x, type = 1L, sample_id = 1L)

## S4 replacement method for signature 'SpatialFeatureExperiment'
spatialGraph(x, type = 1L, MARGIN, sample_id = NULL) <- value

colGraph(x, type = 1L, sample_id = 1L) <- value

rowGraph(x, type = 1L, sample_id = 1L) <- value

annotGraph(x, type = 1L, sample_id = 1L) <- value