Relate points to spatial annotations — getCoordsDfSA • SPATA2

Adds the spatial relation to a spatial annotation to the coordinates data.frame. See details and examples for more.

getCoordsDfSA(
  object,
  ids = idSA(object),
  distance = "dte",
  resolution = recSgsRes(object),
  core = TRUE,
  core0 = FALSE,
  periphery = TRUE,
  angle_span = c(0, 360),
  n_bins_angle = 1,
  dist_unit = getDefaultUnit(object),
  coords_df = NULL,
  variables = NULL,
  format = "wide",
  incl_edge = TRUE,
  drop_na = TRUE,
  verbose = NULL,
  ...
)

getCoordsDfST(
  object,
  id = idST(object),
  width = getTrajectoryLength(object, id = id),
  dist_unit = getDefaultUnit(object),
  resolution = recSgsRes(object),
  outside = TRUE,
  variables = NULL,
  format = "wide",
  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.

ids

Character vector. Specifies the IDs of the spatial annotations of interest.

distance

Distance measure. Specifies the distance from the border of the spatial annotation to the horizon in the periphery up to which the screening is conducted. Defaults to a distance that covers the whole tissue section the spatial annotation is located on using distToEdge(). (This distance must not be exceeded.)

resolution

Distance measure. The resolution with which the expression gradient is inferred. Defaults are platform specific. See more in detail section of recSgsRes().

core

Logical value. If FALSE, data points that lie inside the core of the spatial annotation are removed.

core0

Logical value. If TRUE, dist valus of core data points are set to 0.

angle_span

Numeric vector of length 2. Confines the area screened by an angle span relative to the center of its closest spatial annotation.

n_bins_angle

Numeric value. The number of bins in which observations are categorized in the variable bins_angle.

dist_unit

Character value. Unit in which the distance is computed. Defaults to pixel.

coords_df

Data.frame. If NULL, the default, the coordinates data.frame obtained via getCoordsDf() is used. Else other data.frame of observations can be put in relation to the spatial annotation. Requires numeric variables named x and y in pixel units.

variables

Character vector. The numeric variables to be included in the screening process. Makre sure that the correct matrix is active in the respective assays.

format

Character value. Either 'long' or 'wide'. Defaults to 'wide'. If 'wide' each variable gets a column. If 'long', the data.frame is organized such that a column called variables contains the variable names and a column called 'values' contains the values.

incl_edge

Logical value. If TRUE, the default, the edges of the tissue sections identified by identifyTissueOutline() are used to ensure that the only data points are related to the spatial annotation that are located on the same tissue section as the spatial annotation. Data points that do not share the same tissue section obtain NAs for the created variables.

drop_na

Logical value (only relevant if incl_edge = TRUE). If TRUE, the default, data points that do not share the same tissue section with the spatial annotation are dropped!

verbose

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

(Warning messages will always be printed.)

...

Additional arguments given to joinWithVariables(). Only used if not empty and coords_df is NULL.

Value

Data.frame. See details for more.

Details

The coordinates data.frame as returned by getCoordsDf() with additional variables:

dist: Numeric. The distance of the data point to the outline of the spatial annotation.
dist_unit: Character. The unit in which the distance is computed.
bins_dist: Factor. The bin the data point was assigned to based on its dist value and the resolution parameter. Binwidth is equal to the value of resolution.
angle: Numeric. The angle of the data point to the center of the spatial annotation.
bins_angle: Factor. The bin the data point was assigned to based on its angle value.
rel_loc: Character. Possible values are 'core', if the data point lies inside the spatial annotation, 'periphery' if the data point lies outside of the boundaries of the spatial annotation but inside the area denoted via distance and outside, if the data point lies beyond the screening area (its distance to the spatial annotation boundaries is bigger than the value denoted in distance).
id Character. The ID of the spatial annotation the data points lies closest to. (only relevant in case of length(ids) > 1)
tissue_section Character. The tissue section on which the spatial annotation of variable id is located.

Note

In most scenarios, it does not make sense to relate data points from tissue sections to a spatial annotation that is located on a different tissue section. Hence, the default of this function (incl_edge = TRUE, drop_na = TRUE) is set to simply remove these data points from the output. See examples.

Examples


library(SPATA2)
library(patchwork)
library(tidyverse)

data("example_data")

# Example 1 - One spatial annotation on one tissue section
object <- loadExampleObject("UKF275T", process = TRUE, meta = TRUE)

object <-
 createNumericAnnotations(
   object = object,
   variable = "HM_HYPOXIA",
   threshold = "kmeans_high",
   id = "hypoxia_ann",
   inner_borders = FALSE,
   force1 = TRUE
   )

# default distance = "dte" -> uses distToEdge()
coords_df <- getCoordsDfSA(object, ids = "hypoxia_ann", resolution = "1mm")

p1 <-
  plotSurface(object, "HM_HYPOXIA", pt_clrsp = "inferno") +
  ggpLayerSpatAnnOutline(object, ids = "hypoxia_ann", line_color = "white")

p2 <- plotSurface(coords_df, "dist")

p1 + p2

plotSurface(coords_df, color_by = "bins_dist", pt_clrp = "inferno")
plotSurface(coords_df, color_by = "rel_loc", pt_clrp = "npg")

coords_df_3mm <- getCoordsDfSA(object, ids = "hypoxia_ann", resolution = "2mm")

plotSurface(coords_df_3mm, color_by = "dist") +
  plotSurface(coords_df_3mm, color_by = "rel_loc", pt_clrp = "npg")


## Example 2 - Multiple spatial annotations on one tissue section

object <- loadExampleObject("UKF313T")

necr_ids <- getSpatAnnIds(object, tags = c("compr", "necrotic"), test = "all")

plotSpatialAnnotations(object, ids = necr_ids, line_size = 1, fill = NA)

# considered individually

map(
.x = necr_ids,
.f = function(id){

  coords_df <- getCoordsDfSA(object, ids = id, distance = "dte")

  p1 <-
    plotSurface(coords_df, color_by = "dist") +
    ggpLayerSpatAnnOutline(object, ids = id, line_color = "white") +
    labs(caption = id)

  return(p1)

}
) %>% wrap_plots(., nrow = 2)

# considered alltogether

coords_df <- getCoordsDfSA(object, ids = necr_ids)

plotSurface(coords_df, color_by = "dist") +
  ggpLayerSpatAnnOutline(object, ids = necr_ids)

coords_df <- getCoordsDfSA(object, ids = necr_ids, core0 = TRUE)

plotSurface(coords_df, color_by = "dist") +
  ggpLayerSpatAnnOutline(object, ids = necr_ids)


## Example 3 - Multiple tissue sections

object <- loadExampleObject("LMU_MCI", process = TRUE, meta = TRUE)

plotSurface(object, color_by = "tissue_section") +
  ggpLayerTissueOutline(object)

plotSpatialAnnotations(object, ids = c("inj1", "inj2"))

# the default
coords_df <- getCoordsDfSA(object, ids = "inj1", incl_edge = T, drop_na = T)

plotSurface(coords_df, color_by = "dist") +
  ggpLayerTissueOutline(object)

# drop_na = FALSE
coords_df <- getCoordsDfSA(object, ids = "inj1", incl_edge = T, drop_na = F)

plotSurface(coords_df, color_by = "dist") +
  ggpLayerTissueOutline(object) +
  ggpLayerSpatAnnOutline(object, ids = c("inj1", "inj2"))

# incl_edge = FALSE (does not make sense in this scenario)
coords_df <- getCoordsDfSA(object, ids = "inj1", incl_edge = F)

plotSurface(coords_df, color_by = "dist") +
  ggpLayerTissueOutline(object)

## Example 4 - Using external coordinate data.frames

# get mouse data
object <- example_data$object_lmu_mci_diet
object <- identifyTissueOutline(object)

hemispheres <- ggpLayerTissueOutline(object)
injuries <- ggpLayerSpatAnnOutline(object, ids = c("inj1", "inj2"))

# get sc deconvolution data
sc_input <- example_data$sc_input_mci_lmu

# plot space
p_visium <-
  plotSurface(object, "tissue_section") +
  hemispheres +
  injuries

p_sc <-
  plotSurface(sc_input, color_by = "cell_type", pt_size = 1) +
  hemispheres +
  injuries

p_visium + p_sc

# relate cells to spatial annotations
sc_input_rel <- getCoordsDfSA(object, ids = "inj1", coords_df = sc_input, resolution = "250um")

plotSurface(sc_input_rel, color_by = "dist", pt_size = 1) +
  hemispheres

ggplot(sc_input_rel, mapping = aes(x = bins_dist)) +
 geom_bar(mapping = aes(fill = cell_type), color = "black", position = "fill") +
 theme_classic() +
 scale_color_add_on(aes = "fill", variable = sc_input_rel$cell_type, clrp = "tab20b")