BUG: MapQuery gives aberrant results if reference is subset after RunUMAP

[Alexis-Varin]

Issue Description

Dear Seurat team,
I have encountered a bug when using MapQuery with an object that has been subset after the UMAP coordinates have been generated using RunUMAP with the return.model = TRUE. If that object is being used as a reference in the MapQuery pipeline, the query will have distorded coordinates as is the case below:

both reference and query were merged, the rasterized points are from the reference, solid points from the query

I have found that this is because while the UMAP coordinates are correctly subset, the UMAP model is not, therefore when using the reference, the wrong cells will be used to project the coordinates. Simple fix is to subset the embedding slot of the UMAP model to resolve proper mapping, as is evidenced below:

seu[["umap"]]@misc$model$embedding = seu[["umap"]]@misc$model$embedding[rownames(seu[["umap"]]@cell.embeddings), ]

As can be seen, the query points now align on the clusters they are predicted to.

I hope this will be of great help to many people who like me have pulled their hair trying to figure out why projection was not working.

Best,

Reproducing Code Example

nrow(reference[["umap"]]@cell.embeddings) # 7985, subset object, to remove low quality cells for example
nrow(reference[["umap"]]@misc$model$embedding) # 8574, model is never subset, problem arises

# subset the embeddings from the UMAP model (they are not different from the UMAP)
reference[["umap"]]@misc$model$embedding = reference[["umap"]]@misc$model$embedding[rownames(reference[["umap"]]@cell.embeddings), ]

# proceed with the classic MapQuery pipeline
anchors = FindTransferAnchors(reference = reference, query = query, dims = 1:30, reference.reduction = "pca")

mapquery.res = MapQuery(anchorset = anchors, reference = reference, query = query, refdata = list(celltype = "seurat_clusters"), reference.reduction = "pca", reduction.model = "umap")

Error Message

Additional Comments

No response

Session Info

R version 4.4.3 (2025-02-28)
Platform: x86_64-conda-linux-gnu
Running under: Rocky Linux 8.5 (Green Obsidian)

Matrix products: default
BLAS/LAPACK: /Work/Users/avarin/.conda/envs/scRNA_2026/lib/libopenblasp-r0.3.33.so;  LAPACK version 3.12.0

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
 [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
 [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
 [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
 [9] LC_ADDRESS=C               LC_TELEPHONE=C            
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       

time zone: Europe/Paris
tzcode source: system (glibc)

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] dplyr_1.2.1        future_1.70.0      Seurat_5.5.1       SeuratObject_5.4.0
[5] sp_2.2-1          

loaded via a namespace (and not attached):
  [1] deldir_2.0-4           pbapply_1.7-4          gridExtra_2.3.1       
  [4] rlang_1.2.0            magrittr_2.0.5         RcppAnnoy_0.0.23      
  [7] otel_0.2.0             matrixStats_1.5.0      ggridges_0.5.7        
 [10] compiler_4.4.3         spatstat.geom_3.8-1    png_0.1-9             
 [13] vctrs_0.7.3            reshape2_1.4.5         stringr_1.6.0         
 [16] pkgconfig_2.0.3        fastmap_1.2.0          promises_1.5.0        
 [19] purrr_1.2.2            jsonlite_2.0.0         goftest_1.2-3         
 [22] later_1.4.8            spatstat.utils_3.2-3   irlba_2.3.7           
 [25] parallel_4.4.3         cluster_2.1.8.2        R6_2.6.1              
 [28] ica_1.0-3              stringi_1.8.7          RColorBrewer_1.1-3    
 [31] spatstat.data_3.1-9    reticulate_1.46.0      parallelly_1.48.0     
 [34] spatstat.univar_3.2-0  lmtest_0.9-40          scattermore_1.2       
 [37] Rcpp_1.1.1-1.1         tensor_1.5.1           future.apply_1.20.2   
 [40] zoo_1.8-15             sctransform_0.4.3      httpuv_1.6.17         
 [43] Matrix_1.7-5           splines_4.4.3          igraph_2.3.3          
 [46] tidyselect_1.2.1       abind_1.4-8            codetools_0.2-20      
 [49] spatstat.random_3.4-5  miniUI_0.1.2           spatstat.explore_3.8-0
 [52] listenv_1.0.0          lattice_0.22-9         tibble_3.3.1          
 [55] plyr_1.8.9             shiny_1.14.0           S7_0.2.2              
 [58] ROCR_1.0-12            Rtsne_0.17             fastDummies_1.7.6     
 [61] survival_3.8-6         polyclip_1.10-7        fitdistrplus_1.2-6    
 [64] pillar_1.11.1          KernSmooth_2.23-26     plotly_4.12.0         
 [67] generics_0.1.4         RcppHNSW_0.7.0         ggplot2_4.0.3         
 [70] scales_1.4.0           globals_0.19.1         xtable_1.8-8          
 [73] glue_1.8.1             lazyeval_0.2.3         tools_4.4.3           
 [76] data.table_1.17.8      RSpectra_0.16-2        RANN_2.6.2            
 [79] dotCall64_1.2          cowplot_1.2.0          grid_4.4.3            
 [82] tidyr_1.3.2            nlme_3.1-169           patchwork_1.3.2       
 [85] cli_3.6.6              spatstat.sparse_3.2-0  spam_2.11-4           
 [88] viridisLite_0.4.3      uwot_0.2.4             gtable_0.3.6          
 [91] digest_0.6.39          progressr_0.19.0       ggrepel_0.9.8         
 [94] htmlwidgets_1.6.4      farver_2.1.2           htmltools_0.5.9       
 [97] lifecycle_1.0.5        httr_1.4.8             mime_0.13             
[100] MASS_7.3-65

[BenjaminDEMAILLE]

Your diagnosis is exactly right, and your workaround is now a fix: satijalab/seurat-object#316 makes subsetting a reduction subset the model's embedding with it, so nobody has to know to do it by hand.

I measured it the way you would want a fix measured, by projecting a reference's own cells back through its own model, where each cell should land on its own coordinate. Note that the subset has to not be a prefix of the original, otherwise the first N rows of the stale model still line up and the bug hides:

model	median distance to own coordinate	share of the embedding's spread
stale, 80 rows	3.184	13.7%
subset, 50 rows	0.579	2.5%

That is the same effect as your two plots, in numbers.

The mechanism, for the record: the projection finds the query's neighbours among the reduction's current cells, then reads their coordinates out of the model, so every index past the subset points at a different cell than the one matched. Nothing in the pipeline can notice.

Thank you for chasing it down to the slot; that is what made this a ten-line fix instead of an investigation.

---

Outside contribution: I am not a member of the Seurat dev team, and this comment is not an official answer from the maintainers.