rapids_singlecell.pp.wnn#
- rapids_singlecell.pp.wnn(adata, use_rep, n_pcs=None, *, n_neighbors=20, knn_range=200, l2_norm=True, sd_scale=1.0, cross_constant=0.0001, smooth=False, prune_snn=0.06666666666666667, algorithm='brute', algorithm_kwds=mappingproxy({}), method='umap', rng=None, weight_key='{}_weight', out=False, key_added=None, copy=False)[source]#
Weighted nearest neighbor (WNN) graph across modalities [HHAN+21].
GPU implementation of Seurat’s
FindMultiModalNeighbors. Each cell gets a weight per modality from how well its neighbors there predict its embedding, compared to the other modalities’ neighbors. The multimodal neighbors maximize the weighted sum of per-modality affinity kernels, with widths from shared-nearest-neighbor structure.- Parameters:
- adata
AnnData|MuData Annotated data matrix, or a
MuDataobject whose modalities share the same cells.- use_rep
Sequence[str] |Mapping[str,str] One dimensional reduction per modality, e.g.
['X_pca', 'X_apca'](keys of.obsm, or'X'). A mapping names the modalities; for MuData it maps each modality to an.obsmkey of it, e.g.{'rna': 'X_pca', 'prot': 'X_pca'}.- n_pcs
int|Sequence[int|None] |None(default:None) Number of dimensions to use, per modality or for all (Seurat’s
dims.list).Noneuses all dimensions.- n_neighbors
int(default:20) Number of multimodal neighbors (Seurat’s
k.nn), also used for the modality weights.- knn_range
int(default:200) Neighbors searched per modality, whose union are the multimodal candidates (Seurat’s
knn.range).- l2_norm
bool(default:True) L2-normalize the embeddings of every cell.
- sd_scale
float(default:1.0) Scaling factor of the kernel widths.
- cross_constant
float|Sequence[float] (default:0.0001) Constant to avoid dividing by zero when comparing within- and cross-modality predictions, per modality or for all (Seurat’s cross-modality constant list).
- smooth
bool(default:False) Average the modality scores over each cell’s neighbors in that modality.
- prune_snn
float(default:0.06666666666666667) Jaccard cutoff for edges of the shared nearest neighbor graph (Seurat’s
prune.SNN).- algorithm
Literal['brute','cagra','ivfflat','ivfpq','nn_descent','all_neighbors','mg_ivfflat','mg_ivfpq'] (default:'brute') The kNN search within each modality, see
neighbors().'brute'(default) is exact and bit-identical across runs up toknn_range=256(beyond, cuVS orders exactly tied neighbors arbitrarily).'ivfflat'is much faster, yet closer to exact than Seurat’s Annoy search;'cagra'needsknn_range <= 64.- algorithm_kwds
Mapping[str,Any] (default:mappingproxy({})) Options for the kNN search, see
neighbors(). Incomplete results raise aValueError(for IVF, increasen_probes). For'nn_descent',intermediate_graph_degreedefaults tomax(128, 1.5 * knn_range).- method
Literal['umap','gauss','jaccard'] (default:'umap') Method for the
connectivities, seeneighbors().- rng
int|integer|Sequence[int] |SeedSequence|Generator|BitGenerator|None(default:None) Random seed or
Generatorfor the UMAP connectivities. The supersededrandom_stateargument is still accepted.- weight_key
str|None(default:'{}_weight') Format string for the
.obscolumns of the modality weights, filled with the modality name (the.obsmkey or the mapping key ofuse_rep).'{}:mod_weight'gives muon’s names;Noneskips the weights.- out
GraphAcc|str|dict[str,GraphAcc|str] |bool(default:False) Where to write the graphs. A single accessor
A.obsp['k']writes the connectivities to.obsp['k'], the others to.obsp['k_distances']and.obsp['k_snn'], and the metadata to.uns['k']. A mapping writes only the graphs it names, e.g.{'connectivities': A.obsp['wnn']}. IfTrue, they are returned as aWnnResultand nothing is written. IfFalse, they are written to.obsp['connectivities'],.obsp['distances'],.obsp['snn']and.uns['neighbors'].
- adata
- Return type:
- Returns:
A
WnnResultifout=True, elseNone. Seeoutfor where these are written:- distancessparse matrix of dtype
float32. The
n_neighborsmultimodal neighbors of every cell, excluding itself, with Seurat’s WNN distance of the weighted kernel similarity (0 for the nearest neighbor in all modalities).- connectivitiessparse matrix of dtype
float32. Weighted adjacency matrix of the multimodal neighbors and the cell itself (
n_neighbors + 1as in Scanpy), computed withmethod, forumap()andleiden().- snnsparse matrix of dtype
float32. Seurat’s
wsnngraph, the Jaccard index of the multimodal neighbor sets, with unit diagonal. Seurat clusters on it, e.g.rsc.tl.leiden(adata, obsp='snn'); Leiden counts the diagonal as self-loops, Seurat’s default Louvain ignores it.- weights
.obs[weight_key.format(name)] The weight of each modality per cell.
.uns['neighbors']['params']['modalities']holds each modality’s representation key and number of dimensions. Its standarduse_repandn_pcsentries refer to the first modality with AnnData (for Scanpy’s layout initialization) and map the modalities to them with MuData, as in muon.ingest()rejects WNN references;scanpy.tl.ingest()uses the first modality.- distancessparse matrix of dtype