Single-cell reference mapping with Symphony method

Single-cell reference mapping with Symphony method

Usage

RunSymphonyMap(
  srt_query,
  srt_ref,
  query_assay = NULL,
  ref_assay = srt_ref[[ref_pca]]@assay.used,
  ref_pca = NULL,
  ref_harmony = NULL,
  ref_umap = NULL,
  ref_group = NULL,
  projection_method = c("model", "knn"),
  nn_method = NULL,
  k = 30,
  distance_metric = "cosine",
  vote_fun = "mean",
  verbose = TRUE
)

Arguments

srt_query

An object of class Seurat to be annotated with cell types.

srt_ref

A Seurat object or count matrix representing the reference object. If provided, the similarities will be calculated between cells from the query and reference objects. If not provided, the similarities will be calculated within the query object.

query_assay

The assay to use for the query object. If not provided, the default assay of the query object will be used.

ref_assay

The assay to use for the reference object. If not provided, the default assay of the reference object will be used.

ref_pca

The PCA reduction in the reference object to use for calculating the distance metric.

ref_harmony

The Harmony reduction in the reference object to use for calculating the distance metric.

ref_umap

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

The grouping variable in the reference object. This variable will be used to group cells in the heatmap columns. If not provided, all cells will be treated as one group.

projection_method

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

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. For finite dense inputs using cosine or Euclidean distance, the raw path uses a bounded-memory compiled top-k kernel unless the full distance matrix is requested. Other metrics and sparse inputs retain the existing proxyC path.

k

A number of nearest neighbors to find for each cell in the query object.

distance_metric

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

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

verbose

Whether to print the message. Default is TRUE.

Examples

data(panc8_sub)
panc8_sub <- RunStandardWorkflow(panc8_sub)
#> ℹ [2026-08-30 05:51:42] Start standard processing workflow...
#> ℹ [2026-08-30 05:51:42] Checking a list of <Seurat>...
#> ! [2026-08-30 05:51:42] Data 1/1 of the `srt_list` is "unknown"
#> Warning: Data 1/1 of the `srt_list` is "unknown"
#> ℹ [2026-08-30 05:51:42] Perform `NormalizeData()` with `normalization.method = 'LogNormalize'` on 1/1 of `srt_list`...
#> ℹ [2026-08-30 05:51:42] Perform `FindVariableFeatures()` on 1/1 of `srt_list`...
#> ℹ [2026-08-30 05:51:43] Use the separate HVF from `srt_list`
#> ℹ [2026-08-30 05:51:43] Number of available HVF: 2000
#> ℹ [2026-08-30 05:51:43] Finished check
#> ℹ [2026-08-30 05:51:43] Perform `ScaleData()`
#> ℹ [2026-08-30 05:51:43] Perform pca linear dimension reduction
#> ℹ [2026-08-30 05:51:43] Use stored estimated dimensions 1:26 for Standardpca
#> ℹ [2026-08-30 05:51:44] Perform `Seurat::FindClusters()` with `cluster_algorithm = 'louvain'` and `cluster_resolution = 0.6`
#> ℹ [2026-08-30 05:51:44] Reorder clusters...
#> ℹ [2026-08-30 05:51:44] Skip `log1p()` because `layer = data` is not "counts"
#> ℹ [2026-08-30 05:51:44] Perform umap nonlinear dimension reduction
#> ✔ [2026-08-30 05:51:54] Standard processing workflow completed
srt_ref <- panc8_sub[, panc8_sub$tech != "fluidigmc1"]
srt_query <- panc8_sub[, panc8_sub$tech == "fluidigmc1"]
srt_ref <- RunIntegration(
  srt_ref,
  batch = "tech",
  integration_method = "Harmony"
)
#> Warning: `integration_method` is deprecated; use `integration_methods` instead. It will be removed in scop 1.0.0.
#> ◌ [2026-08-30 05:51:54] Run integration workflow...
#> ℹ [2026-08-30 05:51:55] Split `srt_merge` into `srt_list` by "tech"
#> ℹ [2026-08-30 05:51:55] Checking a list of <Seurat>...
#> ℹ [2026-08-30 05:51:56] Data 1/4 of the `srt_list` has been log-normalized
#> ℹ [2026-08-30 05:51:56] Perform `FindVariableFeatures()` on 1/4 of `srt_list`...
#> ℹ [2026-08-30 05:51:56] Data 2/4 of the `srt_list` has been log-normalized
#> ℹ [2026-08-30 05:51:56] Perform `FindVariableFeatures()` on 2/4 of `srt_list`...
#> ℹ [2026-08-30 05:51:56] Data 3/4 of the `srt_list` has been log-normalized
#> ℹ [2026-08-30 05:51:56] Perform `FindVariableFeatures()` on 3/4 of `srt_list`...
#> ℹ [2026-08-30 05:51:56] Data 4/4 of the `srt_list` has been log-normalized
#> ℹ [2026-08-30 05:51:56] Perform `FindVariableFeatures()` on 4/4 of `srt_list`...
#> ℹ [2026-08-30 05:51:56] Use the separate HVF from `srt_list`
#> ℹ [2026-08-30 05:51:57] Number of available HVF: 2000
#> ℹ [2026-08-30 05:51:57] Finished check
#> ℹ [2026-08-30 05:51:57] Perform `Seurat::ScaleData()`
#> ℹ [2026-08-30 05:51:57] Perform linear dimension reduction("pca")
#> ! [2026-08-30 05:51:57] Some PCA features are absent from scale.data and will be dropped: "NPTX2", "MMP14", "VCAN", "LTB", "ALDH1A3", "NOTCH3", "DEFB1", "COL18A1", "COL5A3", "S100A6", "HABP2", "PLAT", "SERPINF1", "GPX2", "TFPI2", "SRXN1", "CYR61", "NCAM1", …, "AARS2", and "POMC"
#> Warning: Some PCA features are absent from scale.data and will be dropped: "NPTX2", "MMP14", "VCAN", "LTB", "ALDH1A3", "NOTCH3", "DEFB1", "COL18A1", "COL5A3", "S100A6", "HABP2", "PLAT", "SERPINF1", "GPX2", "TFPI2", "SRXN1", "CYR61", "NCAM1", …, "AARS2", and "POMC"
#> ℹ [2026-08-30 05:51:57] Perform Harmony integration
#> ℹ [2026-08-30 05:51:57] Using "Harmonypca" (1:24) as input
#> Warning: restarting interrupted promise evaluation
#> Warning: internal error 1 in R_decompress1 with libdeflate
#> Error in run_harmony(data_mat = data_use[, dims.use, drop = FALSE], meta_data = metavars_df,     vars_use = group.by.vars, verbose = verbose, return_object = TRUE,     ...): lazy-load database '/home/runner/work/_temp/Library/harmony/R/harmony.rdb' is corrupt
CellDimPlot(srt_ref, group.by = c("celltype", "tech"))


# Projection
srt_query <- RunSymphonyMap(
  srt_query = srt_query,
  srt_ref = srt_ref,
  ref_pca = "Harmonypca",
  ref_harmony = "Harmony",
  ref_umap = "HarmonyUMAP2D"
)
#> Error in srt_ref[[ref_pca]]: ‘Harmonypca’ not found in this Seurat object
#>  
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
#>