Find transfer anchors

Source: R/integration.R

Find a set of anchors between a reference and query object. These anchors can later be used to transfer data from the reference to query object using the TransferData object.

FindTransferAnchors(
  reference,
  query,
  normalization.method = "LogNormalize",
  recompute.residuals = TRUE,
  reference.assay = NULL,
  reference.neighbors = NULL,
  query.assay = NULL,
  reduction = "pcaproject",
  reference.reduction = NULL,
  project.query = FALSE,
  features = NULL,
  scale = TRUE,
  npcs = 30,
  l2.norm = TRUE,
  dims = 1:30,
  k.anchor = 5,
  k.filter = 200,
  k.score = 30,
  max.features = 200,
  nn.method = "annoy",
  n.trees = 50,
  eps = 0,
  approx.pca = TRUE,
  mapping.score.k = NULL,
  verbose = TRUE
)

Arguments

reference

Seurat object to use as the reference

query

Seurat object to use as the query

normalization.method

Name of normalization method used: LogNormalize or SCT.

recompute.residuals

If using SCT as a normalization method, compute query Pearson residuals using the reference SCT model parameters.

reference.assay

Name of the Assay to use from reference

reference.neighbors

Name of the Neighbor to use from the reference. Optionally enables reuse of precomputed neighbors.

query.assay

Name of the Assay to use from query

reduction

Dimensional reduction to perform when finding anchors. Options are:

  • pcaproject: Project the PCA from the reference onto the query. We recommend using PCA when reference and query datasets are from scRNA-seq

  • lsiproject: Project the LSI from the reference onto the query. We recommend using LSI when reference and query datasets are from scATAC-seq. This requires that LSI has been computed for the reference dataset, and the same features (eg, peaks or genome bins) are present in both the reference and query. See RunTFIDF and RunSVD

  • rpca: Project the PCA from the reference onto the query, and the PCA from the query onto the reference (reciprocal PCA projection).

  • cca: Run a CCA on the reference and query

reference.reduction

Name of dimensional reduction to use from the reference if running the pcaproject workflow. Optionally enables reuse of precomputed reference dimensional reduction. If NULL (default), use a PCA computed on the reference object.

project.query

Project the PCA from the query dataset onto the reference. Use only in rare cases where the query dataset has a much larger cell number, but the reference dataset has a unique assay for transfer. In this case, the default features will be set to the variable features of the query object that are alos present in the reference.

features

Features to use for dimensional reduction. If not specified, set as variable features of the reference object which are also present in the query.

scale

Scale query data.

npcs

Number of PCs to compute on reference if reference.reduction is not provided.

l2.norm

Perform L2 normalization on the cell embeddings after dimensional reduction

dims

Which dimensions to use from the reduction to specify the neighbor search space

k.anchor

How many neighbors (k) to use when finding anchors

k.filter

How many neighbors (k) to use when filtering anchors. Set to NA to turn off filtering.

k.score

How many neighbors (k) to use when scoring anchors

max.features

The maximum number of features to use when specifying the neighborhood search space in the anchor filtering

nn.method

Method for nearest neighbor finding. Options include: rann, annoy

n.trees

More trees gives higher precision when using annoy approximate nearest neighbor search

eps

Error bound on the neighbor finding algorithm (from RANN or RcppAnnoy)

approx.pca

Use truncated singular value decomposition to approximate PCA

mapping.score.k

Compute and store nearest k query neighbors in the AnchorSet object that is returned. You can optionally set this if you plan on computing the mapping score and want to enable reuse of some downstream neighbor calculations to make the mapping score function more efficient.

verbose

Print progress bars and output

Value

Returns an AnchorSet object that can be used as input to TransferData, IntegrateEmbeddings and MapQuery. The dimension reduction used for finding anchors is stored in the AnchorSet object and can be used for computing anchor weights in downstream functions. Note that only the requested dimensions are stored in the dimension reduction object in the AnchorSet. This means that if dims=2:20 is used, for example, the dimension of the stored reduction is 1:19.

Details

The main steps of this procedure are outlined below. For a more detailed description of the methodology, please see Stuart, Butler, et al Cell 2019. doi: 10.1016/j.cell.2019.05.031 ; doi: 10.1101/460147

  • Perform dimensional reduction. Exactly what is done here depends on the values set for the reduction and project.query parameters. If reduction = "pcaproject", a PCA is performed on either the reference (if project.query = FALSE) or the query (if project.query = TRUE), using the features specified. The data from the other dataset is then projected onto this learned PCA structure. If reduction = "cca", then CCA is performed on the reference and query for this dimensional reduction step. If reduction = "lsiproject", the stored LSI dimension reduction in the reference object is used to project the query dataset onto the reference. If l2.norm is set to TRUE, perform L2 normalization of the embedding vectors.

  • Identify anchors between the reference and query - pairs of cells from each dataset that are contained within each other's neighborhoods (also known as mutual nearest neighbors).

  • Filter low confidence anchors to ensure anchors in the low dimension space are in broad agreement with the high dimensional measurements. This is done by looking at the neighbors of each query cell in the reference dataset using max.features to define this space. If the reference cell isn't found within the first k.filter neighbors, remove the anchor.

  • Assign each remaining anchor a score. For each anchor cell, determine the nearest k.score anchors within its own dataset and within its pair's dataset. Based on these neighborhoods, construct an overall neighbor graph and then compute the shared neighbor overlap between anchor and query cells (analogous to an SNN graph). We use the 0.01 and 0.90 quantiles on these scores to dampen outlier effects and rescale to range between 0-1.

References

Stuart T, Butler A, et al. Comprehensive Integration of Single-Cell Data. Cell. 2019;177:1888-1902 doi: 10.1016/j.cell.2019.05.031 ;

Examples

if (FALSE) {
# to install the SeuratData package see https://github.com/satijalab/seurat-data
library(SeuratData)
data("pbmc3k")

# for demonstration, split the object into reference and query
pbmc.reference <- pbmc3k[, 1:1350]
pbmc.query <- pbmc3k[, 1351:2700]

# perform standard preprocessing on each object
pbmc.reference <- NormalizeData(pbmc.reference)
pbmc.reference <- FindVariableFeatures(pbmc.reference)
pbmc.reference <- ScaleData(pbmc.reference)

pbmc.query <- NormalizeData(pbmc.query)
pbmc.query <- FindVariableFeatures(pbmc.query)
pbmc.query <- ScaleData(pbmc.query)

# find anchors
anchors <- FindTransferAnchors(reference = pbmc.reference, query = pbmc.query)

# transfer labels
predictions <- TransferData(
  anchorset = anchors,
  refdata = pbmc.reference$seurat_annotations
)
pbmc.query <- AddMetaData(object = pbmc.query, metadata = predictions)
}