createGroupAnnotations: Create spatial annotations from a group of data points

In theMILOlab/SPATA2: A Toolbox for Spatial Expression Analysis

Create spatial annotations from a group of data points

Description

Creates spatial annotations based on the spatial extent of a group of data points (spots or cells). See details for more information.

Usage

createGroupAnnotations(
  object,
  grouping,
  group,
  id,
  tags = NULL,
  tags_expand = TRUE,
  use_dbscan = TRUE,
  inner_borders = TRUE,
  eps = recDbscanEps(object),
  minPts = recDbscanMinPts(object),
  min_size = nObs(object) * 0.01,
  force1 = FALSE,
  method_outline = "concaveman",
  alpha = recAlpha(object),
  concavity = 2,
  overwrite = FALSE,
  verbose = NULL
)

Arguments

object	An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.
grouping	Character value. The grouping variable containing the group of interest.
group	Character value. The group of interest.
id	Character value. The ID of the spatial annotation. If NULL, the ID of the annotation is created by combining the string 'spat_ann' with the index the new annotation has in the list of all annotations.
tags	A character vector of tags for the spatial annotation.
tags_expand	Logical value. If TRUE, the tags with which the image annotations are tagged are expanded by the unsuffixed id, the grouping, the group and 'createGroupAnnotations'.
use_dbscan	Logical value. If TRUE, the DBSCAN algorithm is used to identify spatial clusters and outliers before the outline of the spatial annotation is drawn.
inner_borders	Logical value. If TRUE, the algorithm checks whether the annotation requires inner borders and sets them accordingly. If FALSE, only an outer border is created.
eps	Distance measure. Given to eps of dbscan::dbscan(). Determines the size (radius) of the epsilon neighborhood.
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)
min_size	Numeric value. The minimum number of data points a dbscan cluster must have in order not to be discarded as a spatial outlier.
force1	Logical value. If TRUE, spatial sub groups identified by DBSCAN are merged into one cluster. Note: If FALSE (the default), the input for ìd is suffixed with an index to label each spatial annotation created uniquely, regardless of how many are eventually created. E.g. if id = "my_ann" and the algorithm created two spatial annotations, they are named my_ann_1 and my_ann_2.
method_outline	Character value. The method used to create the outline of the spatial annotations. Either 'concaveman' or 'alphahull'. 'concaveman': A fast algorithm that creates concave hulls with adjustable detail. It captures more intricate shapes and is generally computationally efficient, but may produce less smooth outlines compared to alpha shapes. concavity determines the level of detail. 'alphahull': (BETA) Generates an alpha shape outline by controlling the boundary tightness with the alpha parameter. Smaller alpha values produce highly detailed boundaries, while larger values approximate convex shapes. It’s more precise for capturing complex edges but can be computationally more intensive.
alpha	Numeric value. Given to alpha of alphahull::ahull(). Default is platform dependent.
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.
overwrite	Logical value. Must be TRUE to allow overwriting.
verbose	Logical. If TRUE, informative messages regarding the computational progress will be printed. (Warning messages will always be printed.)

Details

The functions filters the coordinates data.frame obtained via getCoordsDf() based on the input of argument grouping and group.

Following filtering, if use_dbscan is TRUE, the DBSCAN algorithm identifies spatial outliers, which are then removed. Furthermore, if DBSCAN detects multiple dense clusters, they can be merged into a single group if force1 is also set to TRUE.

It is essential to note that bypassing the DBSCAN step may lead to the inclusion of individual data points dispersed across the sample. This results in an image annotation that essentially spans the entirety of the sample, lacking the segregation of specific variable expressions. Similarly, enabling force1 might unify multiple segregated areas, present on both sides of the sample, into one group and subsequently, one spatial annotation encompassing the whole sample. Consider to allow the creation of multiple spatial annotations (suffixed with an index) and merging them afterwards via mergeSpatialAnnotations() if they are too close together.

Lastly, the remaining data points are fed into either the concaveman or the alphahull algorithm on a per-group basis. The algorithm calculates polygons outlining the groups of data points. If dbscan_use is FALSE, all data points that remained after the initial filtering are submitted to the algorithm. Subsequently, these polygons are integrated into addSpatialAnnotation() along with the unsuffixed id and tags input arguments. The ID is suffixed with an index for each group.

Value

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

Distance measures

The vignette on distance measures in SPATA2 has been replaced. Click here to read it.

References

P. J. de Oliveira and A. C. P. F. da Silva (2012). alphahull: Generalization of the convex hull of a sample of points in the plane. R package version 2.1. https://CRAN.R-project.org/package=alphahull

Graham, D., & Heaton, D. (2018). concaveman: A very fast 2D concave hull algorithm. R package version 1.1.0. https://CRAN.R-project.org/package=concaveman

See Also

recDbscanEps(), recDbscanMinPts()

Examples

library(SPATA2)
library(tidyverse)

data("example_data")

object <- example_data$object_UKF275T_diet

object <-
 createGroupAnnotations(
   object = object,
   grouping = "bayes_space",
   group = "1",
   id = "bspace1",
   tags = "bspace_ann"
   )

 plotSurface(object, color_by = "bayes_space") +
   ggpLayerSpatAnnOutline(object, tags = "bspace_ann")

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