cellmapper.Neighbors#

class cellmapper.Neighbors(distances, indices, n_targets=None)#

Nearest neighbors results data store.

Adapted from the scib-metrics package: YosefLab/scib-metrics. Extended to support non-square matrices and potentially varying number of neighbors per cell. This class stores the results of nearest neighbor searches and provides methods to compute adjacency matrices and connectivities using various kernels.

Features:#

Multiple connectivity kernels (Gaussian, adaptive Gaussian, inverse distance, etc.)
Support for both square (self-mapping) and non-square (cross-mapping) matrices
Configurable self-edge inclusion for square matrices in connectivity computations
Robust handling of variable neighbor counts and invalid entries

distances#: Array of distances to the nearest neighbors, excluding self-edges. For square matrices, self-edges are automatically removed during initialization to ensure consistent storage format across different k-NN algorithms.

indices#: Array of indices of the nearest neighbors, excluding self-edges. For square matrices, self-edges are automatically removed during initialization to ensure consistent storage format across different k-NN algorithms.

n_targets#: Number of target samples. If None, it is assumed to be the same as the number of samples in the indices array.

Notes

The n_neighbors property always refers to non-self neighbors (self-edges are automatically removed during initialization for consistent storage). When self-edges are included via connectivity methods with self_edges=True, the resulting arrays will have shape (n_samples, n_neighbors + 1), but the n_neighbors property remains unchanged.

Attributes table#

`is_square`	Whether this represents a square matrix (self-mapping).
`knn_graph_distances`	Return the sparse weighted adjacency matrix of distances.
`n_neighbors`	Number of neighbors.
`n_samples`	Number of samples (cells).
`n_targets`
`shape`	Shape of the adjacency/graph matrices (n_samples, n_targets).
`distances`
`indices`

Methods table#

`boolean_adjacency`([dtype, self_edges])	Construct a boolean adjacency matrix from neighbor indices.
`knn_graph_connectivities`([kernel, ...])	Compute connectivities using the specified kernel.

Attributes#

Neighbors.is_square#: Whether this represents a square matrix (self-mapping).

Neighbors.knn_graph_distances#

Return the sparse weighted adjacency matrix of distances.

Parameters:: dtype – Data type for the matrix values.
Returns:: csr_matrix Sparse matrix of distances (shape: n_samples x n_targets).

Neighbors.n_neighbors#: Number of neighbors.

Neighbors.n_samples#: Number of samples (cells).

Neighbors.n_targets: int | None = None#

Neighbors.shape#: Shape of the adjacency/graph matrices (n_samples, n_targets).

Neighbors.distances: ndarray#

Neighbors.indices: ndarray#

Methods#

Neighbors.boolean_adjacency(dtype=<class 'numpy.float64'>, self_edges=False)#

Construct a boolean adjacency matrix from neighbor indices.

Parameters:

dtype (default: <class 'numpy.float64'>) – Data type for the matrix values.
self_edges (bool (default: False)) – Control self-edges (diagonal entries) for square matrices (self-mapping). If None (default), uses False for self-mapping (scanpy style) and None for cross-mapping. This controls whether or not the kernel used to compute the connectivities is supplied with self-edges. It does not determine whether the final connectivity matrix has self edges. For example, the umap kernel expectes self-edges, but does not produce them in the final connectivity matrix.

Return type:

csr_matrix

Returns:

csr_matrix Boolean adjacency matrix (shape: n_samples x n_targets), with 1 for each neighbor relationship.

Neighbors.knn_graph_connectivities(kernel='gauss', self_edges=False, dtype=<class 'numpy.float64'>, **kwargs)#

Compute connectivities using the specified kernel.