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 MuData object 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 .obsm key 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). None uses 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 to knn_range=256 (beyond, cuVS orders exactly tied neighbors arbitrarily). 'ivfflat' is much faster, yet closer to exact than Seurat’s Annoy search; 'cagra' needs knn_range <= 64.

algorithm_kwds Mapping[str, Any] (default: mappingproxy({}))

Options for the kNN search, see neighbors(). Incomplete results raise a ValueError (for IVF, increase n_probes). For 'nn_descent', intermediate_graph_degree defaults to max(128, 1.5 * knn_range).

method Literal['umap', 'gauss', 'jaccard'] (default: 'umap')

Method for the connectivities, see neighbors().

rng int | integer | Sequence[int] | SeedSequence | Generator | BitGenerator | None (default: None)

Random seed or Generator for the UMAP connectivities. The superseded random_state argument is still accepted.

weight_key str | None (default: '{}_weight')

Format string for the .obs columns of the modality weights, filled with the modality name (the .obsm key or the mapping key of use_rep). '{}:mod_weight' gives muon’s names; None skips 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']}. If True, they are returned as a WnnResult and nothing is written. If False, they are written to .obsp['connectivities'], .obsp['distances'], .obsp['snn'] and .uns['neighbors'].

Return type:

AnnData | MuData | WnnResult | None

Returns:

A WnnResult if out=True, else None. See out for where these are written:

distancessparse matrix of dtype float32.

The n_neighbors multimodal neighbors of every cell, excluding itself, with Seurat’s WNN distance (1−s)/2 of the weighted kernel similarity s (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 + 1 as in Scanpy), computed with method, for umap() and leiden().

snnsparse matrix of dtype float32.

Seurat’s wsnn graph, 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 standard use_rep and n_pcs entries 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.