Plot IAS rideplot

Plots gene expression changes against the distance to an the image annotation using the desing of ridgeplots.

plotIasRidgeplot(
  object,
  id,
  variables,
  distance = NA_integer_,
  n_bins_circle = NA_integer_,
  binwidth = getCCD(object),
  angle_span = c(0, 360),
  n_bins_angle = 1,
  method_gs = NULL,
  smooth_span = 0.3,
  unit = getSpatialMethod(object)@unit,
  round = 2,
  clrp = NULL,
  clrp_adjust = NULL,
  line_color = "black",
  line_size = 1.5,
  fill = NULL,
  alpha = 1,
  normalize_by = "sample",
  summarize_with = "mean",
  include_area = FALSE,
  display_border = TRUE,
  bcsp_exclude = NA_integer_,
  border_linealpha = 0.75,
  border_linecolor = "black",
  border_linesize = 1,
  border_linetype = "dashed",
  x_nth = 7L,
  sc_input = NULL,
  ncol = 1,
  nrow = NULL,
  overlap = 0.5,
  strip_pos = "right",
  verbose = NULL,
  ...
)

plotIasRidgeplotSC(
  object,
  id,
  sc_input,
  distance = NA_integer_,
  n_bins_circle = NA_integer_,
  binwidth = getCCD(object),
  angle_span = c(0, 360),
  smooth_span = 0.3,
  unit = getSpatialMethod(object)@unit,
  round = 2,
  scale = FALSE,
  clrp = NULL,
  clrp_adjust = NULL,
  alpha = 1,
  fill = NULL,
  line_color = "black",
  line_size = 1.5,
  include_area = FALSE,
  display_border = TRUE,
  border_linealpha = 0.75,
  border_linecolor = "black",
  border_linesize = 1,
  border_linetype = "dashed",
  strip_pos = "right",
  overlap = 0.5,
  free_y = TRUE,
  x_nth = 7L,
  ncol = 1,
  nrow = NULL,
  verbose = NULL,
  ...
)

Arguments

object

An object of class spata2.

id

Character value. The ID of the image annotation of interest.

variables

Character vector. All numeric variables (meaning genes, gene-sets and numeric features) that are supposed to be included in the screening process.

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.)

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().

smooth_span

Numeric value. Controls the degree of smoothing. Given to argument span of stats::loess().

unit

Character value. Specifies the desired unit.

round

Numeric value or FALSE. If numeric, given to digits of base::round(). Rounds transformed values before they are returned.

clrp

Character value. Specifies the color palette to be used to represent groups of discrete variables. Run validColorPalettes() to obtain valid input options.

clrp_adjust

Named character vector or NULL. If character, it adjusts the color palette that is used to represent the groups. Names of the input vector must refer to the group and the respective named element denotes the color with which to represent the group.

line_color

Character. Affects color of the main lines of the plot.

line_size

Numeric value. Specifies the thicknes of the lines with which the trajectory dynamics are displayed.

summarize_with

Character value. Either 'mean' or 'median'. Specifies the function with which the bins are summarized.

display_border

Logical value. If TRUE, displays a vertical line to highlight where the border of the image annotation runs.

bcsp_exclude

Character value containing name(s) of barcode-spots to be excluded from the analysis.

border_linealpha, border_linecolor, border_linesize, border_linetype

Given to ggplot2::geom_vline(). Adjusts appearance of the vertical line that represents the border of the image annotation.

x_nth

Numeric value. If the number of breaks/labels on the x-axis becomes too high x_nth can be used to reduce it. If x_nth is 1, every label is kept. If 2, every second label is kept. If 3, every third label is kept. And so on.

sc_input

Data.frame that contains the results from single cell deconvolution. Must have at least three columns:

  • x : numeric. Position of cell on the x axis in pixel.,

  • y : numeric. Position of cell on the y axis in pixel.,

  • cell_type : factor Cell type of the cell.

nrow, ncol

Numeric values or NULL. Used to arrange multiple plots.

verbose

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

(Warning messages will always be printed.)

...

Needed arguments that depend on the input/unit combination. If one of both is 'px', argument object must be specified.

scale

Logical value. If TRUE, density of cell types is scaled to make them comparable. Else, the absolute values defined by count/unit^2 is plotted.

Value

A ggplot.

Details

In conjunction with argument id which provides the ID of the image annotation of interest the arguments distance, binwidth, n_bins_circle, angle_span and n_bins_angle can be used to specify the exact area that is screened as well as the resolution of the screening.

How the algorithm works: During the IAS-algorithm the barcode spots are binned according to their localisation to the image annotation. Every bin's mean expression of a given gene is then aligned in an ascending order - mean expression of bin 1, mean expression of bin 2, ... up to the last bin, the bin with the barcode-spots that lie farest away from the image annotation. This allows to infer the gene expression changes in relation to the image annotation and to screen for genes whose expression changes resemble specific biological behaviors. E.g. linear ascending: gene expression increases linearly with the distance to the image annotation. E.g. immediate descending: gene expression is high in close proximity to the image annotation and declines logarithmically with the distance to the image annotation.

How circular binning works: To bin barcode-spots according to their localisation to the image annotation three parameters are required:

  • distance: The distance from the border of the image annotation to the horizon in the periphery up to which the screening is conducted. Unit of the distance is pixel as is the unit of the image.

  • binwidth: The width of every bin. Unit is pixel.

  • n_bins_circle: The number of bins that are created.

Regarding parameter n_bins_circle: The suffix _circle is used for one thing to emphasize that bins are created in a circular fashion around the image annotation (although the shape of the polygon that was created to encircle the image annotation is maintained). Additionally, the suffix is needed to delineate it from argument n_bins_angle which can be used to increase the resolution of the screening.

These three parameters stand in the following relation to each other:

  1. n_bins_circle = distance / binwidth

  2. distance = n_bins_circle * binwidth

  3. binwidth = distance / n_bins_circle

Therefore, only two of the three arguments must be specified as the remaining one is calculated. We recommend to stick to the first option: Specifying distance and binwidth and letting the function calculate n_bins_circle.

Once the parameters are set and calculated the polygon that is used to define the borders of the image annotation (the one you draw with createImageAnnotation()) is repeatedly expanded by the distance indicated by parameter binwidth. The number of times this expansion is repeated is equal to the parameter n_bins_circle. Every time the polygon is expanded, the newly enclosed barcode-spots are binned (grouped) and the bin is given a number that is equal to the number of the expansion. Thus, barcode-spots that are adjacent to the image annotation are binned into bin 1, barcode spots that lie a distance of binwidth away are binned into bin 2, etc.

Note that the function plotSurfaceIas() allows to visually check if your input results in the desired screening.

How the screening works: For every gene that is included in the screening process every bin's mean expression is calculated and then aligned in an ascending order - mean expression of bin 1, mean expression of bin 2, ... up to the last bin, namely the bin with the barcode-spots that lie farest away from the image annotation. This allows to infer the gene expression changes in relation to the image annotation and to screen for genes whose expression changes resemble specific biological behaviors. The gene expression change is fitted to every model that is included. (Use showModels() to visualize the predefined models of SPATA2). A gene-model-fit is evaluated twofold:

  • Residuals area over the curve: The area under the curve (AUC) of the residuals between the inferred expression changes and the model is calculated, normalized against the number of bins and then subtracted from 1.

  • Pearson correlation: The inferred expression changes is correlated with the model. (Correlation as well as the corresponding p-value depend on the number of bins!)

Eventually, the mean of the RAOC and the Correlation for every gene-model-fit is calculated and stored as the IAS-Score.

Distance measures

Several functions in SPATA2 have arguments that take distance input. To specifically refer to a distance the unit must be specified. There are three ways to create valid input for these arguments.

1. In pixel:

There are two valid input options to specify the distance in pixel:

  • numeric: Single numeric values, e.g. arg_input = c(2, 3.554, 69, 100.67). If no unit is specified the input will be interpreted as pixels.

  • character: Suffixed with 'px', e.g. arg_input = c('2px', '3.554px', '69px', '100.67px')

Note: The unit pixel (px) is used for distances as well as for areas. If pixel refers to a distance the pixel side length is meant. If pixel refers to an area the number of pixels is meant.

2. According to the Systeme international d`unites (SI):

Specifying distances in SI units e.g. arg_input = c('2mm', '4mm') etc. requires the input to be a character as the unit must be provided as suffix. Between the numeric value and the unit must be no empty space! Valid suffixes can be obtained using the function validUnitsOfLengthSI().

3. As vectors of class unit:

Behind the scenes SPATA2 works with the units package. Input is converted into vectors of class units. Therefore, input can be directly provided this way: arg_input = units::set_unit(x = c(2,4), value = 'mm') Note that pixel is not a valid unit in the units package. If you want to specify the input in pixel you have to use input option 1. In pixel.