Identify tissue outline

Identifies and stores the spatial boundaries of the tissue section(s). Then it assigns observations to their respective section. Note that information about the boundaries of the tissue is crucial for many SPATA2 intern function. This information should not be missing in the SPATA2 object. See details for more.

identifyTissueOutline(object, ...)

# S4 method for class 'SPATA2'
identifyTissueOutline(
  object,
  method = "obs",
  minPts = recDbscanMinPts(object),
  eps = recDbscanEps(object),
  img_name = activeImage(object),
  concavity = 2,
  verbose = NULL,
  ...
)

# S4 method for class 'SpatialData'
identifyTissueOutline(
  object,
  method,
  img_name = activeImage(object),
  eps = recDbscanEps(object),
  minPts = recDbscanMinPts(object),
  concavity = 2,
  verbose = TRUE,
  ...
)

# S4 method for class 'HistoImage'
identifyTissueOutline(object, verbose = TRUE)

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.

method

Character value. Defines the origin based on which the outline is computed. Either 'image' or 'obs'.

minPts

Numeric value. Given to dbscan::dbscan(). Determines the number of minimum points required in the eps neighborhood for core points (including the point itself)

eps

Distance measure. Given to eps of dbscan::dbscan(). Determines the size (radius) of the epsilon neighborhood.

img_name

Character value. The name of the image of interest. If NULL, the active image is chosen by default. Either way, must be one of getImageNames().

concavity

Numeric value. Given to argument concavity of concaveman::concaveman(). Determines the relative measure of concavity. 1 results in a relatively detailed shape, Infinity results in a convex hull. You can use values lower than 1, but they can produce pretty crazy shapes.

verbose

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

(Warning messages will always be printed.)

Value

The updated input object, containing the added, removed or computed results.

Details

In case of method = obs, DBSCAN is applied to categorize the data points of the object based on their spatial proximity, grouping those that are close enough to be deemed part of a single contiguous tissue section. Data points that are isolated and situated at a significant distance from others are identified as spatial outliers.The resulting classifications are saved in a tissue_section variable within the object's meta data.frame. Afterwards, polygons are created to outline the groups of data points which represent a tissue section. See example 'method = obs'.

In case of method = image the object must contain an image named as indicated by the input of argument img_name. Furthermore, the results of identifyPixelContent() for that image are required. If img_name specifies multiple images, the function iterates over all of them. Since results of both methods are stored in different locations, the object can contain results of both methods. When extracting the tissue outline via getTissueOutlineDf() or ggpLayerTissueOutline() use argument method to decide on which results to use. See example 'method = image'.

DBSCAN input

For objects derived from the Visium platform with a fixed center to center distance, we recommend to set eps = getCCD(object, unit = "px")*1.25 and minPts = 3 which has worked well for us. For objects derived from platforms that do not rely on a fixed grid of data points (MERFISH, SlideSeq, etc.) we recommend the average minimal distance between the data points times 10 for eps and minPts = 25, which might require manual adjustments. The function defaults to these recommendations using recDbscanEps() and recDbscanMinPts() by default. This can, of course, be overwritten manually by the user by specifying the parameters otherwise! Note that you can visualize the results with plotSurface(object, color_by = 'tissue_section') and repeat the process with different parameter input to overwrite the last results untill you are satisfied with the output.

Examples


library(SPATA2)
library(ggplot2)

data("example_data")

obj1 <- loadExampleObject("UKF275T")

obj2 <- loadExampleObject("LMU_MCI")

# example: 'method = obs'
obj1 <- identifyTissueOutline(obj1, method = "obs")

obj2 <- identifyTissueOutline(obj2, method = "obs")

## visualize the categorization of spots with the new meta variable 'tissue_section'

plotSurface(obj1, color_by = "tissue_section") # one single contiguous section

plotSurface(obj2, color_by = "tissue_section") # two contiguous sections

## visualize the outline

df1_obs <- getTissueOutlineDf(obj1)

ggplot(df1_obs, mapping = aes(x, y, group = section)) +
 geom_polygon(fill = NA, color = "black")

df2_obs <- getTissueOutlineDf(obj2)

ggplot(df2_obs, mapping = aes(x, y, group = section)) +
 geom_polygon(fill = NA, color = "black")

# example 'method = image'

activeImage(obj1)

obj1 <- identifyPixelContent(obj1, img_name = "image1") # image processing needed
obj1 <- identifyTissueOutline(obj1, method = "image", img_name = "image1")

plotImage(obj1, outline = T)

df1_img <- getTissueOutlineDf(obj1, method = "image")

ggplot(mapping = aes(x, y, group = section)) +
 geom_polygon(fill = NA, color = "black", data = df1_obs) +
 geom_polygon(fill = NA, color = "red", data = df1_img)