get_img_ann_helper: Obtain image annotation screening data.frame
In kueckelj/SPATA2: A Toolbox for Spatial Gene Expression Analysis

get_img_ann_helper

R Documentation

Obtain image annotation screening data.frame

Description

Extracts a data.frame that contains information about barcode-spots needed for analysis related to imageAnnotationScreening().

Usage

get_img_ann_helper(
  object,
  id,
  distance = NA_integer_,
  n_bins_circle = NA_integer_,
  binwidth = getCCD(object),
  angle_span = c(0, 360),
  n_bins_angle = 1,
  variables = NULL,
  method_gs = NULL,
  summarize_by = FALSE,
  summarize_with = "mean",
  normalize_by = "sample",
  normalize = FALSE,
  remove_circle_bins = FALSE,
  remove_angle_bins = FALSE,
  rename_angle_bins = FALSE,
  bcsp_exclude = NULL,
  drop = TRUE,
  verbose = NULL,
  ...
)

Arguments

`object`	An object of class `spata2`.
`id`	Character value. The ID of the image annotation of interest.
`distance`	Distance value. Specifies the distance from the border of the image annotation to the horizon in the periphery up to which the screening is conducted. (See details for more.) - See details of `?is_dist` for more information about distance values.
`n_bins_circle`	Numeric value or vector of length 2. Specifies how many times the area is buffered with the value denoted in `binwidth`. (See details for more.)
`binwidth`	Distance value. The width of the circular bins to which the barcode-spots are assigned. We recommend to set it equal to the center-center distance: `binwidth = getCCD(object)`. (See details for more.) - See details of `?is_dist` for more information about distance values.
`angle_span`	Numeric vector of length 2. Confines the area screened by an angle span relative to the center of the image annotation. (See details fore more.)
`n_bins_angle`	Numeric value. Number of bins that are created by angle. (See details for more.)
`variables`	Character vector. All numeric variables (meaning genes, gene-sets and numeric features) that are supposed to be included in the screening process.
`method_gs`	Character value. The method according to which gene sets will be handled specified as a character of length one. This can be either 'mean or one of 'gsva', 'ssgsea', 'zscore', or 'plage'. The latter four will be given to gsva::GSVA().
`summarize_with`	Character value. Either 'mean' or 'median'. Specifies the function with which the bins are summarized.
`normalize_by`	Character value or FALSE. If character, there are two options: `normalize_by` = 'sample': Values are normalized across the whole sample. `normalize_by` = 'bins_angle': Values are normalized within each angle bin. This only has an effect if `n_bins_angle` is bigger than 1.
`normalize`	Logical. If set to TRUE values will be scaled to 0-1. Hint: Variables that are uniformly expressed can not be scaled and are discarded.
`bcsp_exclude`	Character value containing name(s) of barcode-spots to be excluded from the analysis.
`drop`	Logical value. If TRUE, unused levels of the bins_circle variables are dropped.
`verbose`	Logical. If set to TRUE informative messages regarding the computational progress will be printed. (Warning messages will always be printed.)
`...`	Used to absorb deprecated arguments or functions.

Value

The final output depends on the input for variables and summarize_by.

By default (both arguments are NULL) the returned data.frame contains barcode-spots as observations/rows and variables that describe their position to the image annotation denoted with id. This includes the variables bins_circle, bins_order, angle, bins_angle. Their content depends on the set up via the arguments distance, binwidth and n_bins_circle.

Coordinates data.frame vs. Inferred expression changes:

If argument variables is a character the denoted variables are joined to the data.frame via joinWith(). If the set of variables contains only numeric ones (genes, gene-sets and numeric features) the function argument summarize_by can be set up in three different ways:

summarize_by = FALSE: Values are not summarized. The output is a coordinates data.frame with each observation/row corresponding to a barcode spots with additional information of its relation to the image annotation denoted in id.
summarize_by = 'bins_circle' Values of each variable area summarized by each circular expansion of the polygon. This results in data.frame with a column named bins_circle containing the names of the bin (Core, Circle 1, Circle 2, Circle 3, ..., Circle n, Outside) and 1 column per variable that contain the summarized expression value by circle bin. Visualization of the concept can be obtained using plotIasLineplot(..., facet_by = 'variables')
summarize_by = c('bins_circle', 'bins_angle')) Values of each area are summarized by each circular expansion as well as by angle-bin. Output data.frame is similar to summarize_by = 'bins_circle' apart from having an extra column identifying the angle-bins. Adding 'bins_circle' is only useful if n_bins_circle is bigger than 1. Visualization of the concept can be obtained by using plotIasLineplot(..., facet_by = 'bins_angle').