smoother.weights

Calculate spatial weight matrix from coordinates, histology images, and transcriptomic data

Classes

SpatialWeightMatrix

Spatial weight matrix.

Functions

coordinate_to_weights_knn_sparse(coords[, k, ...])

Calculate spatial weight matrix using k-nearest neighbours (sklearn).

coordinate_to_weights_dist_sparse(coords[, ...])

Calculate spatial weight matrix using distance band (sklearn).

coordinate_to_weights_knn_dense(coords[, k, ...])

Calculate spatial weight matrix using k-nearest neighbours.

coordinate_to_weights_dist_dense(coords[, ...])

Calculate spatial weight matrix using distance band.

sparse_weights_to_inv_cov(weights, model[, rho, ...])

Convert a spatial weight matrix to an inverse covariance matrix. Sparse version.

weights_to_inv_cov(weights, model[, rho, standardize])

Convert a spatial weight matrix to an inverse covariance matrix.

_standardize_inv_cov(inv_cov)

Standardize the inverse covariance matrix.

Module Contents

smoother.weights.coordinate_to_weights_knn_sparse(coords, k=6, symmetric=True, row_scale=True)

Calculate spatial weight matrix using k-nearest neighbours (sklearn).

Convert spatial coordinate to a spatial weight matrix where non-zero entries represent interactions among k-nearest neighbours. Sparse tensor version.

Parameters:

  • coords (2D array) – Spatial coordinates, num_spot x 2 (or 3).

  • k (int) – Number of nearest neighbours to keep.

  • symmetric (bool) – If True only keep mutual neighbors.

  • row_scale (bool) – If True scale row sum of the spatial weight matrix to 1.

Returns:

A sparse 2D tensor containing spatial weights, num_spot x num_spot.

Return type:

weights

smoother.weights.coordinate_to_weights_dist_sparse(coords, scale_coords=True, radius_cutoff=1.0, band_width=0.1, dist_metric='euclidean', row_scale=True)

Calculate spatial weight matrix using distance band (sklearn).

Convert spatial coordinate to a spatial weight matrix where non-zero entries represent interactions among neighbours defined by the distane threshold. Sparse tensor version.

Parameters:

  • coords (2D array) – Spatial coordinates, num_spot x 2 (or 3).

  • scale_coords (bool) – If True, scale coordinates to [0, 1].

  • radius_cutoff (float) – Distance threshold (in the same unit as the coords input).

  • band_width (float) – Specify the width of the Gaussian kernel, which is proportional to the inverse rate of weight distance decay.

  • dist_metric (str) – Distance metric.

  • row_scale (bool) – If True scale row sum of the spatial weight matrix to 1.

Returns:

A sparse 2D tensor containing spatial weights, num_spot x num_spot.

Return type:

weights

smoother.weights.coordinate_to_weights_knn_dense(coords, k=6, symmetric=True, row_scale=True)

Calculate spatial weight matrix using k-nearest neighbours.

Convert spatial coordinate to a spatial weight matrix where non-zero entries represent interactions among k-nearest neighbours.

Parameters:

  • coords (2D array) – Spatial coordinates, num_spot x 2 (or 3).

  • k (int) – Number of nearest neighbours to keep.

  • symmetric (bool) – If True only keep mutual neighbors.

  • row_scale (bool) – If True scale row sum of the spatial weight matrix to 1.

Returns:

A 2D tensor containing spatial weights, num_spot x num_spot.

Return type:

weights

smoother.weights.coordinate_to_weights_dist_dense(coords, scale_coords=True, q_threshold=0.001, band_width=0.1, dist_metric='euclidean', row_scale=True)

Calculate spatial weight matrix using distance band.

Convert spatial coordinate to a spatial weight matrix where non-zero entries represent interactions among neighbours defined by the distane threshold.

Parameters:

  • coords (2D array) – Spatial coordinates, num_spot x 2 (or 3).

  • scale_coords (bool) – If True, scale coordinates to [0, 1].

  • q_threshold (float) – Distance quantile threshold. Number of nonzero entries in the weight matrix (edges) = num_spot^2 * q_threshold.

  • band_width (float) – Specify the width of the Gaussian kernel, which is proportional to the inverse rate of weight distance decay.

  • dist_metric (str) – Distance metric.

  • row_scale (bool) – If True scale row sum of the spatial weight matrix to 1.

Returns:

A 2D tensor containing spatial weights, num_spot x num_spot.

Return type:

weights

smoother.weights.sparse_weights_to_inv_cov(weights, model, rho=1, standardize=False, return_sparse=False)

Convert a spatial weight matrix to an inverse covariance matrix. Sparse version.

Calculate the covariance structure using spatial weights. Different spatial process models impose different structures. Check model descriptions for more details.

Parameters:

  • weights (Sparse tensor) – Spatial weight matrix (sparse), num_spot x num_spot.

  • model (str) – Spatial process model to use, can be one of ‘sma’,’sar’, ‘isar’, ‘car’, ‘icar’.

  • rho (float) – Spatial autocorrelation parameter.

  • standardize (bool) – If True, return the standardized inverse covariance matrix (inv_corr).

  • return_sparse (bool) – If True, return a sparse tensor. Note that the inverse covariance matrix of the SMA model is not sparse in general.

Returns:

An inverse covariance (precision) matrix, num_spot x num_spot.

Return type:

inv_cov (2D tensor)

smoother.weights.weights_to_inv_cov(weights, model, rho=1, standardize=False)

Convert a spatial weight matrix to an inverse covariance matrix.

Calculate the covariance structure using spatial weights. Different spatial process models impose different structures. Check model descriptions for more details.

Parameters:

  • weights (2D tensor) – Spatial weight matrix, num_spot x num_spot.

  • model (str) – Spatial process model to use, can be one of ‘sma’,’sar’, ‘isar’, ‘car’, ‘icar’.

  • rho (float) – Spatial autocorrelation parameter.

  • standardize (bool) – If True, return the standardized inverse covariance matrix (inv_corr).

Returns:

An inverse covariance (precision) matrix, num_spot x num_spot.

Return type:

inv_cov (2D tensor)

smoother.weights._standardize_inv_cov(inv_cov)

Standardize the inverse covariance matrix.

When the inverse covariance matrix is singular, the matrix will be normalized instead to have diagonal elements of 1 (i.e. return normalized laplacian for ‘icar’ model).

class smoother.weights.SpatialWeightMatrix

Spatial weight matrix.

The adjacency matrix that specifies connectivities and interactions between each pair of spots.

swm

Unscaled spatial weight matrix.

Type:

sparse tensor

swm_scaled

Spatial weight matrix scaled with external information (e.g., expression, histology).

Type:

sparse tensor

inv_covs

Cached inverse covariance matrices under different model settings (for debugging).

Type:

dict

config

Configurations.

Type:

dict

swm = None
swm_scaled = None
inv_covs
config
_check_swm_stats(scaled=False, verbose=True) → None

Check spatial weight matrix statistics.

calc_weights_knn(coords, k=6, symmetric=True, row_scale=False, verbose=True) → None

Calculate spatial weight matrix using k-nearest neighbours.

Convert spatial coordinate to a spatial weight matrix where non-zero entries represent interactions among k-nearest neighbours.

Parameters:

  • coords (2D array) – Spatial coordinates, num_spot x 2 (or 3).

  • k (int) – Number of nearest neighbours to keep.

  • symmetric (bool) – If True only keep mutual neighbors.

  • row_scale (bool) – If True scale row sum of the spatial weight matrix to 1.

  • verbose (bool) – If True, print out weights summary.

calc_weights_dist(coords, scale_coords=True, radius_cutoff=1.0, band_width=0.1, dist_metric='euclidean', row_scale=True, verbose=True) → None

Calculate spatial weight matrix using distance band.

Convert spatial coordinate to a spatial weight matrix where non-zero entries represent interactions among neighbours defined by the distane threshold.

Parameters:

  • coords (2D array) – Spatial coordinates, num_spot x 2 (or 3).

  • scale_coords (bool) – If True, scale coordinates to [0, 1].

  • radius_cutoff (float) – Distance threshold (in the same unit as the coords input).

  • band_width (float) – Specify the width of the Gaussian kernel, which is proportional to the inverse rate of weight distance decay.

  • dist_metric (str) – Distance metric.

  • row_scale (bool) – If True scale row sum of the spatial weight matrix to 1.

  • verbose (bool) – If True, print out weights summary.

scale_by_similarity(pairwise_sim: smoother.utils.torch.Tensor, row_scale=False, return_swm=False, verbose=True) → None

Scale spatial weight matrix by external pairwise similarity.

Parameters:

  • pairwise_sim (2D tensor) – External pairwise similarity, num_spot x num_spot.

  • row_scale (bool) – If True, scale rowsums of spatial weight matrix to be 1.

  • return_swm (bool) – Whether to output the scaled spatial weight matrix.

  • verbose (bool) – If True, print out weights summary.

scale_by_identity(spot_ids, boundary_connectivity=0, row_scale=False, return_swm=False, verbose=True) → None

Scale spatial weight matrix by spot identity.

Parameters:

  • spot_ids (1D array) – Spot identity of length num_spot.

  • boundary_connectivity (float) – Connectivity of spots with different identities. If 0 (default), no interaction across identities.

scale_by_expr(expr, dist_metric='cosine', reduce='pca', dim=10, row_scale=False, verbose=True) → None

Scale weight matrix using transcriptional similarity.

Parameters:

  • expr (2D array) – Spatial gene expression count matrix, num_genes x num_spot.

  • dist_metric (str) – Distance metric.

  • reduce (str) – If PCA, calculate distance on the reduced PCA space.

  • dim (int) – Number of dimension of the reduced space.

  • row_scale (bool) – If True, scale rowsums of spatial weight matrix to be 1.

  • verbose (bool) – If True, print out weights summary.

scale_by_histology(coords, image, scale_factors: dict, dist_metric='euclidean', reduce='pca', dim=10, row_scale=False, verbose=True) → None

Calculate pairwise histology similarity between spots.

Parameters:

  • coords (2D array) – Spatial coordinate matrix (in fullres pixel), num_spot x 2.

  • image (3D array) – Histology image, num_pixel x num_pixel x num_channel.

  • scale_fators (dict) –

    The JSON dictionary from 10x Visium’s scalefactors_json.json ‘spot_diameter_fullres’ (float): Spot size (fullres) ‘tissue_hires_scalef’ (float): Scale factor that transforms fullres

    image to the given image.

  • reduce (str) – If PCA, calculate distance on the reduced PCA space.

  • dist_metric (str) – Distance metric used to calculate similarity.

  • dim (int) – Number of dimension of the reduced space.

  • row_scale (bool) – If True, scale rowsums of spatial weight matrix to be 1.

  • verbose (bool) – If True, print out weights summary.

get_inv_cov(model, rho=1, cached=True, standardize=False, return_sparse=True)

Calculate or extract cached inverse covariance matrix.

Parameters:

  • model (str) – The spatial process model, can be one of ‘sma’,’sar’, ‘car’, ‘icar’.

  • rho (float) – The spatial autocorrelation parameter.

  • return_sparse (bool) – If True, return sparse matrix.