liana.pp.spatial_neighbors

liana.pp.spatial_neighbors#

liana.pp.spatial_neighbors(adata, bandwidth=None, cutoff=0.1, max_neighbours=100, kernel='gaussian', set_diag=False, zoi=0, standardize=False, reference=None, spatial_key='spatial', key_added='spatial', inplace=True, verbose=False)#

Generate spatial connectivity weights using Euclidean distance.

Parameters:
adata AnnData | MuData

Annotated data object (AnnData or MuData) with spatial coordinates in .obsm[spatial_key].

bandwidth float | None (default: None)

Denotes signaling length and controls the maximum distance at which two spots/cells are considered. Corresponds to the units in which spatial coordinates are expressed.

cutoff float | None (default: 0.1)

Values below this cutoff will be set to 0.

max_neighbours int (default: 100)

Maximum nearest neighbours to be considered when generating spatial connectivity weights. Essentially, the maximum number of edges in the spatial connectivity graph. Note that whenever more than max_neighbours spots fall within cutoff this truncates the neighbourhood, and the resulting connectivities are no longer symmetric. Clamped down to the number of available locations (reference when given, else the spots themselves), since fewer neighbours than that cannot be found; logged under verbose=True.

kernel Literal['gaussian', 'exponential', 'linear', 'misty_rbf'] (default: 'gaussian')

Kernel function used to generate connectivity/proximity weights. It controls the shape of the connectivity weights. The following options are available: [‘gaussian’, ‘exponential’, ‘linear’, ‘misty_rbf’].

set_diag bool (default: False)

Logical, sets connectivity diagonal to 0 if False. Default is False.

zoi float (default: 0)

Zone of indifference. Values below this cutoff will be set to np.inf.

standardize bool (default: False)

Whether to (l1) standardize spatial proximities (connectivities) so that they sum to 1. This plays a role when weighing border regions prior to downstream methods, as the number of spots in the border region (and hence the sum of proximities) is smaller than the number of spots in the center. Relevant for methods with unstandardized scores (e.g. product). Default is False.

reference ArrayLike | None (default: None)

Reference coordinates to use when generating spatial connectivity weights. If None, uses the spatial coordinates in adata.obsm[spatial_key]. This is only relevant if you want to use a different set of coordinates to generate spatial connectivity weights.

spatial_key str (default: 'spatial')

Key in adata.obsm that contains the spatial coordinates.

key_added str (default: 'spatial')

Key to add to adata.obsp if inplace = True. If reference is not None, key will be added to adata.obsm and any existing .obsp entry under the same key is left untouched – methods that read .obsp would then keep using that older graph, so a warning is emitted.

inplace bool (default: True)

Whether to store results in place, or else to return them.

verbose bool | None (default: False)

Verbosity flag. False, the default, hides progress and info messages but still warns about data-altering conditions; True shows both; None silences everything, warnings included.

Notes

This function is adapted from mistyR, and is set to be consistent with the squidpy.gr.spatial_neighbors function in the squidpy package.

Return type:

ndarray | None

Returns:

If inplace = False, returns an np.array with spatial connectivity weights. Otherwise, modifies the adata object with the following key:

Raises:

  • ValueError – If no cutoff or bandwidth are provided

  • AssertionError – If the provided spatial_key is not in adata.obs or if kernel function is not valid.

Examples

Weights every pair of spots by how close they are, giving the spatially informed methods the neighbourhood they operate over:

>>> import liana as li
>>> adata = li.ds.generate_toy_spatial()
>>> li.pp.spatial_neighbors(adata, bandwidth=500)

bandwidth is required and sets the distance over which proximity decays – liana.pp.query_bandwidth() helps pick it – while kernel sets the shape of that decay.