scanpy.pp.bbknn

Contents

scanpy.pp.bbknn#

scanpy.pp.bbknn(adata, neighbors_within_batch=3, n_pcs=None, *, batches='obs.batch', use_rep=None, transformer=None, metric='euclidean', metric_kwds=mappingproxy({}), trim=None, rng=None, key_added=None, copy=False)[source]#

Compute a batch balanced neighborhood graph of observations [Polański et al., 2019].

Batch balanced kNN alters the kNN procedure to identify each cell’s top neighbors in each batch separately instead of the entire cell pool with no accounting for batch. The nearest neighbors of each batch are then merged to create a final list of neighbors for the cell, which aligns batches in a quick and lightweight manner.

Use this as an alternative to neighbors(): it writes the same fields, so all downstream steps (e.g. umap() or leiden()) work unchanged. This CPU implementation is based on the rapids-singlecell package.

Array type support#

Array type

supported

… experimentally in dask Array

numpy.ndarray

✅

❌

scipy.sparse.{csr,csc}_{array,matrix}

✅

❌
Parameters:
adata AnnData

Annotated data matrix.

neighbors_within_batch int (default: 3)

How many top neighbors to report for each batch. The total number of neighbors is this number times the number of batches, which then serves as the basis for the construction of a symmetrical matrix of connectivities.

n_pcs int | None (default: None)

Use this many PCs. If n_pcs==0 use .X if use_rep is None.

batches AdRef | str (default: 'obs.batch')

adata.obs column name discriminating between the batches.

use_rep LayerAcc | MultiAcc | str | None (default: None)

Use the indicated representation: a LayerAcc (e.g. A.X, A.layers[...]) or MultiAcc (e.g. A.obsm[...], A.varm[...]). A str is resolve()d to one of those if scanpy.settings.preset is ScanpyV2Preview, otherwise interpreted as 'X' or a key of .obsm.

If None, the representation is chosen automatically: For .n_vars < N_PCS (default: 50), .X is used, otherwise the PCA representation (.obsm['X_pca'], or .obsm['pca'] if it was computed under ScanpyV2Preview). If it is not present, it’s computed with default parameters or n_pcs if present.

transformer KnnTransformerLike | Literal['pynndescent', 'sklearn'] | None (default: None)

kNN search backend following the API of KNeighborsTransformer. One index is built per batch and queried with all observations, so its n_neighbors is ignored in favor of neighbors_within_batch. See Using other kNN libraries in Scanpy for more details. Also accepts the following known options:

None (the default)

Behavior depends on data size. For small data, we will calculate exact kNN, otherwise we use PyNNDescentTransformer

'pynndescent'

PyNNDescentTransformer

metric Literal['cityblock', 'cosine', 'euclidean', 'l1', 'l2', 'manhattan'] | Literal['braycurtis', 'canberra', 'chebyshev', 'correlation', 'dice', 'hamming', 'jaccard', 'kulsinski', 'mahalanobis', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'yule'] | Callable[[ndarray, ndarray], float] (default: 'euclidean')

A known metric’s name or a callable that returns a distance.

ignored if transformer is an instance.

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

Options for the metric.

ignored if transformer is an instance.

trim int | None (default: None)

Trim each cell’s neighbors to these many top connectivities. May help with population independence and improve the tidiness of clustering. The lower the value, the more independent the individual populations, at the cost of a more conserved batch effect. If None, this is set to 10 times the total number of neighbors. Set to 0 to skip trimming.

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

Random number generation to control stochasticity.

If a type:SeedLike value, it’s used to seed a new random number generator; If a numpy.random.Generator, rng’s state will be directly advanced; If None, a non-reproducible random number generator is used. See numpy.random.default_rng() for more details.

The default value matches legacy scanpy behavior and will change to None in scanpy 2.0.

ignored if transformer is an instance.

key_added str | None (default: None)

If not specified, the neighbors data is stored in .uns['neighbors'], distances and connectivities are stored in .obsp['distances'] and .obsp['connectivities'] respectively. If specified, the neighbors data is added to .uns[key_added], distances are stored in .obsp[f'{key_added}_distances'] and connectivities in .obsp[f'{key_added}_connectivities'].

copy bool (default: False)

Return a copy instead of writing to adata.

Return type:

AnnData | None

Returns:

Returns None if copy=False, else returns an AnnData object. Sets the following fields:

adata.obsp['distances' | f'{key_added}_distances']scipy.sparse.csr_matrix (dtype float)

Distance matrix of the batch balanced nearest neighbors search. Each row (cell) has neighbors_within_batch × n_batches - 1 non-zero entries: its nearest neighbors in each batch, excluding the cell itself.

adata.obsp['connectivities' | f'{key_added}_connectivities']scipy.sparse.csr_matrix (dtype float)

Weighted adjacency matrix of the neighborhood graph of data points. Weights should be interpreted as connectivities.

adata.uns['neighbors' | key_added]dict

neighbors parameters.

Examples

>>> import scanpy as sc
>>> adata = sc.datasets.pbmc68k_reduced()
>>> adata.obs["batch"] = adata.obs["phase"]
>>> sc.pp.bbknn(adata, batches="obs.batch")
>>> sc.tl.umap(adata)

See also

neighbors() Using other kNN libraries in Scanpy

Contents