This function performs single-cell reference mapping using the K-nearest neighbor (KNN) method. It takes two single-cell datasets as input: srt_query and srt_ref. The function maps cells from the srt_query dataset to the srt_ref dataset based on their similarity or distance.
Usage
RunKNNMap(
srt_query,
srt_ref,
query_assay = NULL,
ref_assay = NULL,
ref_umap = NULL,
ref_group = NULL,
features = NULL,
nfeatures = 2000,
query_reduction = NULL,
ref_reduction = NULL,
query_dims = 1:30,
ref_dims = 1:30,
projection_method = c("model", "knn"),
nn_method = NULL,
k = 30,
distance_metric = "cosine",
vote_fun = "mean"
)Arguments
- srt_query
An object of class Seurat storing the query cells.
- srt_ref
An object of class Seurat storing the reference cells.
- query_assay
A character string specifying the assay name for the query cells. If not provided, the default assay for the query object will be used.
- ref_assay
A character string specifying the assay name for the reference cells. If not provided, the default assay for the reference object will be used.
- ref_umap
A character string specifying the name of the UMAP reduction in the reference object. If not provided, the first UMAP reduction found in the reference object will be used.
- ref_group
A character string specifying a metadata column name in the reference object to use for grouping.
- features
A character vector specifying the features to be used for calculating the distance metric. If not provided, the function will use the variable features calculated by the Seurat package.
- nfeatures
A integer specifying the number of highly variable features to be calculated if
featuresis not provided.- query_reduction
A character string specifying the name of a dimensionality reduction in the query object to use for calculating the distance metric.
- ref_reduction
A character string specifying the name of a dimensionality reduction in the reference object to use for calculating the distance metric.
- query_dims
A numeric vector specifying the dimension indices from the query reduction to be used for calculating the distance metric.
- ref_dims
A numeric vector specifying the dimension indices from the reference reduction to be used for calculating the distance metric.
- projection_method
A character string specifying the projection method to use. Options are "model" and "knn". If "model" is selected, the function will try to use a pre-trained UMAP model in the reference object for projection. If "knn" is selected, the function will directly find the nearest neighbors using the distance metric.
- nn_method
A character string specifying the nearest neighbor search method to use. Options are "raw", "annoy", and "rann". If "raw" is selected, the function will use the brute-force method to find the nearest neighbors. If "annoy" is selected, the function will use the Annoy library for approximate nearest neighbor search. If "rann" is selected, the function will use the RANN library for approximate nearest neighbor search. If not provided, the function will choose the search method based on the size of the query and reference datasets.
- k
A number of nearest neighbors to find for each cell in the query object.
- distance_metric
A character string specifying the distance metric to use for calculating the pairwise distances between cells. Options include: "pearson", "spearman", "cosine", "correlation", "jaccard", "ejaccard", "dice", "edice", "hamman", "simple matching", and "faith". Additional distance metrics can also be used, such as "euclidean", "manhattan", "hamming", etc.
- vote_fun
A character string specifying the function to be used for aggregating the nearest neighbors in the reference object. Options are "mean", "median", "sum", "min", "max", "sd", "var", etc. If not provided, the default is "mean".
Examples
data(panc8_sub)
srt_ref <- panc8_sub[, panc8_sub$tech != "fluidigmc1"]
srt_query <- panc8_sub[, panc8_sub$tech == "fluidigmc1"]
srt_ref <- integration_scop(
srt_ref,
batch = "tech",
integration_method = "Seurat"
)
#> ℹ [2025-09-20 13:43:03] Run Seurat integration...
#> ℹ [2025-09-20 13:43:03] Spliting `srt_merge` into `srt_list` by column "tech"...
#> ℹ [2025-09-20 13:43:04] Checking a list of <Seurat> object...
#> ! [2025-09-20 13:43:04] Data 1/4 of the `srt_list` is "unknown"
#> ℹ [2025-09-20 13:43:04] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on the data 1/4 of the `srt_list`...
#> ℹ [2025-09-20 13:43:06] Perform `Seurat::FindVariableFeatures()` on the data 1/4 of the `srt_list`...
#> ! [2025-09-20 13:43:06] Data 2/4 of the `srt_list` is "unknown"
#> ℹ [2025-09-20 13:43:06] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on the data 2/4 of the `srt_list`...
#> ℹ [2025-09-20 13:43:08] Perform `Seurat::FindVariableFeatures()` on the data 2/4 of the `srt_list`...
#> ! [2025-09-20 13:43:08] Data 3/4 of the `srt_list` is "unknown"
#> ℹ [2025-09-20 13:43:08] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on the data 3/4 of the `srt_list`...
#> ℹ [2025-09-20 13:43:10] Perform `Seurat::FindVariableFeatures()` on the data 3/4 of the `srt_list`...
#> ! [2025-09-20 13:43:10] Data 4/4 of the `srt_list` is "unknown"
#> ℹ [2025-09-20 13:43:10] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on the data 4/4 of the `srt_list`...
#> ℹ [2025-09-20 13:43:12] Perform `Seurat::FindVariableFeatures()` on the data 4/4 of the `srt_list`...
#> ℹ [2025-09-20 13:43:12] Use the separate HVF from srt_list
#> ℹ [2025-09-20 13:43:12] Number of available HVF: 2000
#> ℹ [2025-09-20 13:43:13] Finished check
#> ℹ [2025-09-20 13:43:14] Perform FindIntegrationAnchors
#> Warning: Different features in new layer data than already exists for scale.data
#> Warning: Different features in new layer data than already exists for scale.data
#> Warning: Different features in new layer data than already exists for scale.data
#> Warning: Different features in new layer data than already exists for scale.data
#> ℹ [2025-09-20 13:43:36] Perform integration(Seurat)
#> Warning: Layer counts isn't present in the assay object; returning NULL
#> Warning: Different cells in new layer data than already exists for scale.data
#> Warning: Layer counts isn't present in the assay object; returning NULL
#> Warning: Different cells in new layer data than already exists for scale.data
#> Warning: Layer counts isn't present in the assay object; returning NULL
#> ℹ [2025-09-20 13:43:44] Perform ScaleData
#> ℹ [2025-09-20 13:43:44] Perform linear dimension reduction ("pca")
#> ℹ [2025-09-20 13:43:45] Perform FindClusters ("louvain")
#> ℹ [2025-09-20 13:43:45] Reorder clusters...
#> ! [2025-09-20 13:43:45] Using `Seurat::AverageExpression()` to calculate pseudo-bulk data for <Assay>
#> ℹ [2025-09-20 13:43:45] Perform nonlinear dimension reduction (umap)
#> ℹ [2025-09-20 13:43:45] Non-linear dimensionality reduction (umap) using (Seuratpca) dims (1-11) as input
#> ℹ [2025-09-20 13:43:50] Non-linear dimensionality reduction (umap) using (Seuratpca) dims (1-11) as input
#> ✔ [2025-09-20 13:43:56] Run Seurat integration done
CellDimPlot(
srt_ref,
group.by = c("celltype", "tech")
)
#> Warning: No shared levels found between `names(values)` of the manual scale and the
#> data's fill values.
#> Warning: No shared levels found between `names(values)` of the manual scale and the
#> data's fill values.
# Set the number of threads for RcppParallel
# details see: ?RcppParallel::setThreadOptions
# if (requireNamespace("RcppParallel", quietly = TRUE)) {
# RcppParallel::setThreadOptions()
# }
# Projection
srt_query <- RunKNNMap(
srt_query = srt_query,
srt_ref = srt_ref,
ref_umap = "SeuratUMAP2D"
)
#> ℹ [2025-09-20 13:43:56] Use the features to calculate distance metric
#> Error in CheckDataType(data = GetAssayData5(srt_query, layer = "data", assay = query_assay, verbose = FALSE)): argument "object" is missing, with no default
ProjectionPlot(
srt_query = srt_query,
srt_ref = srt_ref,
query_group = "celltype", ref_group = "celltype"
)
#> Error in srt_query[[query_reduction]]: ‘ref.embeddings’ not found in this Seurat object
#>