add_paraview {mistyR} | R Documentation

## Generate and add a paraview to the current view composition

### Description

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

### 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(i,j) = exp(-d(i,j)^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(i,j) = exp(-d(i,j)/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(i,j) = 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.

### Value

A mistyR view composition with added paraview with parameter `l`.

### See Also

`create_initial_view()` for starting a view composition with an intraview only.

Other view composition functions: `add_juxtaview()`, `add_views()`, `create_initial_view()`, `create_view()`, `remove_views()`

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

    # preview
    str(misty.views[["paraview.10"]])

[Package mistyR version 1.2.1 Index]