getSpatialAnnotations: Obtain list of SpatialAnnotation objects

In theMILOlab/SPATA2: A Toolbox for Spatial Expression Analysis

Obtain list of SpatialAnnotation objects

Description

Extracts a list of objects of class SpatialAnnotation.

Usage

getSpatialAnnotations(object, ...)

## S4 method for signature 'SPATA2'
getSpatialAnnotations(
  object,
  ids = NULL,
  class = NULL,
  tags = NULL,
  test = "any",
  add_image = containsImage(object),
  expand = 0,
  square = FALSE,
  error = FALSE,
  ...
)

## S4 method for signature 'SpatialData'
getSpatialAnnotations(
  object,
  ids = NULL,
  class = NULL,
  tags = NULL,
  test = "any",
  add_image = containsImage(object),
  expand = 0,
  square = FALSE,
  error = FALSE,
  ...
)

Arguments

object	An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.
...	Used to absorb deprecated arguments or functions.
class	Character vector or NULL. If character, defines the subtypes of spatial annotations to consider. Must be a combination of c('Group', 'Image' 'Numeric').
tags	Character vector or NULL. If character, the tags for the image annotation selection. See section Selection of spatial annotations for more information.
test	Character value. One of c('any'. 'all', 'identical', 'not_identical', 'none'). Specifies how input for tags is used to select spatial annotations. See section Selection of spatial annotations for more information.
add_image	Logical. If TRUE, the area of the histology image that is occupied by the annotated structure is added to the SpatialAnnotation object in slot @image. Dimensions of the image can be adjusted with square and expand.
expand	Specifies image expansion. An image that is cropped based on an image annotation centers around the image annotation. If expand = 0, the default, the dimensions of the image, that is width/x-axis and height/y-axis, are set to include only the image annotation area and nothing more. Using expand, the cropped image section can be adjusted. See section Expansion of cropped image sections for more information.
square	Logical value. Most image annotations come in variable shapes and have different horizontal and vertical diameters. Therefore, height and width of the image section are usually not equal. If square = TRUE, the cropped section of the image that contains the annotated structure is forced into a square: the bigger diameter of both is taken as default. E.g. if the horizontal diameter of the image annotation is 1mm and the vertical diameter is 1.5mm, the output image will have height and width of 1.5mm. That is, in terms of coordinates, an x-range and a y-range of 1.5mm. Processing of the image output depending on argument expand happens afterwards.
error	Logical. If TRUE and the input is invalid the function throws an error.
strictly	Logical. If TRUE, only barcodes of spots that are strictly interior to the area of an spatial annotation are added to the output. If FALSE, barcodes of spots that are on the relative interior of the area or are vertices of the border are added, too.

Value

A list of objects of class SpatialAnnotation.

Expansion of cropped image sections

The argument expand is a versatile way, to specify how a cropped image section is extracted. If you want the cropped image as is, specify expand = 0. Else, there are multiple options. In general, expand takes three kinds of values, namely percentages, distances and distance exclamations.

• Percentage: A string suffixed with %. E.g. expand = '50%' adds 50% of the distance from the center to the border of the image annotation to the image frame.

• Distance measures: In pixel or European units of length. E.g. expand = list(x = '1mm') expands the x-axis on both sides with 1mm. ⁠expand = list(x = c('0.5mm', 1.5mm')⁠ expands the x-axis on the left side with 0.5mm and on the right side with 1.5mm.

• Exclam distance measures: Distance measure with an exclamation mark suffix. E.g. expand = '1mm!' centers the image and forces an axis length of 1 millimeter. (Example 5)

Depending on how the values are specified different parts of the image can be expanded.

Single values, like expand = 50, are recycled: Every end of each image axis is expanded by 50 pixel. (Example 2)

Vectors of length two, like expand = c('1mm', '2mm'), are recycled: The beginning of each axis is expanded by 1 millimeter. The end of each axis is expanded by 2mm. (Example 3)

Named lists can be more precise. expand = list(x = c('1mm', '0.5mm'), y = c('0.25mm', '1mm')). Applies the vectors to expand the corresponding axis. (Example 4)

Using exclam input the side of the axis must not be specified as the axis is fixed as a whole. E.g expand = list(x = '1mm!', y = '2mm!') results in the same output as ⁠expand = list(x = c('1mm!', '1mm!'), y = c('2mm!', '2mm!')⁠.

Selection of spatial annotations

Selection of spatial annotations via the arguments ids, class, tags and test works in three steps:

First, if ids is a character it prefilters the annotations by ID and only the specified ones are submitted to the next steps. If it is NULL, all annotations are submitted to the next steps.

Secondd, if class is a character it filters the annotations remaining after the first step by their class. If NULL, the step is skipped.

Third, if tags is a character it is used in combination with test to select from the spatial annotations that remain after the second step based on the meta data they are tagged with. There are multiple options:

1. Argument test set to 'any' or 1: To be included, an image annotation must be tagged with at least one of the input tags.

2. Argument test set to 'all' or 2: To be included, an image annotation must be tagged with all of the input tags. Can contain tags that are not specified.

3. Argument test set to 'identical' or 3: To be included, an image annotation must be tagged with all of the input tags. Can not be tagged with anything else.

4. Argument test set to not_identical or 4: To be included, an image annotation must not be tagged with the combination of input tags.

5. Argument test set to 'none' or 5: To be included, an image annotation must not contain any of the input tags.

If tags is NULL, the step is skipped. Therefore, if ids, class and tags are all NULL, which is the default, all annotations are selected as all subsetting steps are skipped. Eventually, the remaining spatial annotations are submitted to whatever the respective function does.

Note

To test how the extracted image section looks like depending on input for argument square and expand use plotSpatialAnnotations(..., encircle = FALSE).

theMILOlab/SPATA2 documentation built on Feb. 8, 2025, 11:41 p.m.