Generate and add a paraview to the current view composition

The paraview captures the expression of all markers in the broader tissue structure.

Usage

add_paraview(
  current.views,
  positions,
  l,
  zoi = 0,
  family = c("gaussian", "exponential", "linear", "constant"),
  approx = 1,
  nn = NULL,
  prefix = "",
  cached = FALSE,
  verbose = TRUE
)

Arguments

current.views: the current view composition.
positions: a data.frame, tibble or a matrix with named coordinates in columns and rows for each spatial unit ordered as in the intraview.
l: effective radius of influence of expression in the broader tissue structure.
zoi: spatial units with distance smaller than the zone of indifference will not be taken into account when generating the paraview.
family: the family f functions used to generate weights. (see Details)
approx: rank of the Nyström approximation matrix. (see Details)
nn: the number of spatial units to be used for approximating the paraview using a fast nearest neighbor search. (see Details)
prefix: a prefix to add to the column names.
cached: a logical indicating whether to cache the calculated view after the first calculation and to reuse a previously cached view if it already exists for this sample.
verbose: a logical controlling the verbosity of the output of the function during execution.

Value

A mistyR view composition with added paraview with parameter l.

Details

The paraview is generated by weighted sum of the expression of all spatial units for each marker. The weights for each spatial unit i are dependent on the family which can be one of "gaussian", "exponential", "linear" or "constant".

If "gaussian" the weights are calculated based on the distance to the spatial unit j and the parameter l using the radial basis function $$w_{ij} = e^{-\frac{d_{ij}^2}{l^2}}$$

The parameter l here denotes the "effective" radius of influence.

If "exponential" the weights are calculated based on the distance to the spatial unit j and the parameter l using the exponential function $$w_{ij} = e^{-\frac{d_{ij}}{l}}$$

The parameter l here denotes signaling length. For more information consult Oyler-Yaniv et. al. Immunity 46(4) 2017.

If "linear" the weights are calculated based on the distance to the spatial unit j and the parameter l using the linear function $$w_{ij} = 1- d(i,j)/l$$

The parameter l here denotes the intersect of the linear function. For distances larger than l the weight is equal to 0.

If "constant" the weights are always 1. The parameter l here denotes the number of nearest neighbors to take into account if nn is not defined.

Since the generation of the paraview requires the calculation of pairwise distances of all spatial units it can take a significant amount of computation time. The parameters approx and nn can be set to speed up the calculation by approximation. The approximation can be achieved by using the Nyström low-rank approximation method or by limiting the calculation of the paraview to a number of nearest neighbors around each spatial unit.

If the value of approx is between 0 and 1 it will be interpreted as fraction of the number of spatial units. Discrete values above 1 will be interpreted as the size of the approximation block. The number of nearest neighbors nn around each spatial unit are determined using a fast nearest neighbor search.

If both approx and nn have non-null values, nn has priority and an approximation based on fast nearest neighbor search will be used to generate the paraview.

Examples

# Create a view composition of an intraview and a paraview with radius 10.

library(dplyr)

# get the expression data
data("synthetic")
expr <- synthetic[[1]] %>% select(-c(row, col, type))
# get the coordinates for each cell
pos <- synthetic[[1]] %>% select(row, col)

# compose
misty.views <- create_initial_view(expr) %>% add_paraview(pos, l = 10)
#> 
#> Generating paraview

# preview
str(misty.views[["paraview.10"]])
#> List of 2
#>  $ abbrev: chr "para.10"
#>  $ data  :'data.frame':	4205 obs. of  11 variables:
#>   ..$ ECM  : num [1:4205] 6.98 15.05 17.37 18.4 19.93 ...
#>   ..$ ligA : num [1:4205] 13.2 12.9 13.6 14.3 14.7 ...
#>   ..$ ligB : num [1:4205] 1.29 2.31 2.78 3 3.16 ...
#>   ..$ ligC : num [1:4205] 9.56 18.52 20.42 20.97 21.99 ...
#>   ..$ ligD : num [1:4205] 17 15.1 16.1 16.9 17.5 ...
#>   ..$ protE: num [1:4205] 14 26.6 28.1 31.5 33.2 ...
#>   ..$ protF: num [1:4205] 28.1 27.7 29 30.9 32.7 ...
#>   ..$ prodA: num [1:4205] 4.37 5.24 5.04 5.61 5.69 ...
#>   ..$ prodB: num [1:4205] 0.816 1.659 1.948 2.093 2.076 ...
#>   ..$ prodC: num [1:4205] 3.87 7.29 8.23 8 8.61 ...
#>   ..$ prodD: num [1:4205] 5.64 6.01 5.98 6.51 6.64 ...