Combined umap for 1 cell lineage, retrieving latent representation

[nhgopee]

Thank you for this very useful package. I am comparing mouse and human and have a few questions regarding the combined umap, retrieving the latent representation and optimising memory usage for GenePairFinder.

1. When I do the analysis across all cell lineages, there is very good overlap of the main cell lineages in the combined umap between human and mouse skin. However, when subsetting to specific cell lineages, such as fibroblast, the combined umap is very fragmented, with 1 cell type forming several split clusters and the overlap between the 2 species is less informative. I have tried to test different iterations, varying: resolutions and defining keys in SAMAP as well as neighbours from keys in sm.run but this has not made much difference. Is there any other way I could address this to make the clusters in the umap restricted to predefined cell types?

2. Is there a way to retrieve the latent representation of the combined umap. Samap.adata currently returns X_umap only. I am wondering about including the pca/wpca in the adata if possible?

3. I am very keen to use GenePairFinder but have hit memory limit very quickly when running this (up to 200GB) even on the smaller data subset.

[ryan-moreno]

Did you figure out the answer to your question 2? I am also trying to do this. From looking through the SAMap code, it seems that variable wpca around line 1777 of mapping.py or variable D at line 864 of mapping.py may be the projection into the combined lower dimensional manifold that we're looking for, but I'm not confident about it.

[atarashansky]

Thanks for the questions — answering all three with updates for v3.0.0:

1. Fragmented UMAP on lineage subsets — This is expected behaviour when subsetting. SAMap builds the cross-species manifold from the full gene-homology graph; when you subset to a single lineage the signal-to-noise ratio drops and the remaining homology edges may not carry enough structure to stitch subtypes cleanly. A few things worth trying:

• Run SAMap on the full dataset, then subset the combined result rather than running SAMap on the subset.
• If you must run on subsets, increase cross_species_k (default 20) in sm.run() to pull in more cross-species neighbours per cell.
• Use neigh_from_keys={'hu': True, 'ms': True} with keys set to your fibroblast subtype annotation — this forces within-species neighbourhoods to respect your labels.

2. Latent representation — @ryan-moreno is correct that wpca is the joint embedding, but in v3.0.0 it's computed transiently inside samap.core.projection._mapping_window_fast and discarded after building the kNN graph. The combined UMAP is computed directly from the graph (sm.samap.adata.obsp['connectivities']), not from a stored embedding. If you need the wPCA for your own downstream use:

from samap.core.projection import precompute_projection_inputs, _mapping_window_fast
pre = precompute_projection_inputs(sm.sams, sm.gnnm_refined, sm.gns_dict)
mdata = _mapping_window_fast(pre, sm.gnnm_refined, sm.gns_dict, sm.sams)
wpca = mdata["wPCA"]  # (N_total × npcs_total) joint embedding
sm.samap.adata.obsm["X_wpca"] = wpca

Alternatively, any graph-based embedding (UMAP, diffusion maps, graph-Laplacian eigenvectors) computed from sm.samap.adata.obsp['connectivities'] is a valid latent representation of the stitched manifold.

3. GenePairFinder memory — v3.0.0 (PR #174) rewrote the core mapping path from N²→N memory scaling, but GenePairFinder still materialises per-cluster-pair expression blocks. Workarounds: (a) use find_genes(n1, n2) for specific cluster pairs instead of find_all(), (b) subset your SAM objects to the clusters of interest before constructing GenePairFinder.

Closing — please reopen if the wPCA extraction snippet doesn't work on your data.