smoother.weights

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

Classes

SpatialWeightMatrix

Spatial weight matrix.

Functions

`normalize_minmax`(x[, min_zero, return_scale])	Normalize data to [0, 1] or [-1, 1].
`_z_score`(features)	Z-score standardization.
`_pca`(features, dim)	Dimension reduction by PCA.
`calc_feature_similarity_sparse`(features, indices[, ...])	Calculate pairwise feature similarity between spots for a given set of spot pairs.
`calc_feature_similarity`(features[, dist_metric, ...])	Calculate pairwise feature similarity between spots.
`get_histology_vector`(image, x_pixel, y_pixel, ...[, ...])	Get the histology image vector of one spot.
`calc_histology_similarity_sparse`(coords, indices, ...)	Calculate pairwise histology similarity between spots for a given set of points.
`calc_histology_similarity`(coords, image, scale_factors)	Calculate pairwise histology similarity between spots.
`quantile_feature_similarity_neighbor`(features, coords, k)	Calculate cosine similarity of features between physical k-nearest neighbors.
`quantile_feature_similarity_decay`(features, coords[, ...])	Calculate cosine similarity of features between physical neighbors of varying degrees.
`get_neighbor_quantile_value_by_k`(sq_mat, coords[, ...])	Extract values of neighboring pairs of spots from the square matrix.
`plot_similarity_cdf`(df_k[, title, k])	Plot cumulative distribution of pairwise cosine similarity between neighboring spots.
`plot_similarity_decay`(df_all[, title, plot_type])	Plot decay of pairwise cosine similarity between neighboring spots.
`_mono_exp`(x, alpha, beta)
`estimate_decay_rate`(x, y[, return_all_params])	Estimate decay rate of a mono-exponential decay function.
`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.normalize_minmax(x, min_zero=True, return_scale=False)

Normalize data to [0, 1] or [-1, 1].

Parameters:

x (2D array) – data to be normalized.
min_zero (bool) – If True, set column minimum to 0.
return_scale (bool) – If True, return the scaling factor.

smoother.weights._z_score(features): Z-score standardization.

smoother.weights._pca(features, dim): Dimension reduction by PCA.

smoother.weights.calc_feature_similarity_sparse(features: torch.Tensor, indices: torch.Tensor, dist_metric='cosine', reduce='none', dim=10, nonneg=False, return_type='flat')

Calculate pairwise feature similarity between spots for a given set of spot pairs.

Similarity s is transformed from distance d by 1) Cosine similarity: s = (1 - d) (if nonneg, (1 - d).clamp(min = 0)) 2) Others: s = exp(- d^2/(2 * band_width^2)))

Parameters:

features (2D tensor) – Feature matrix, num_feature x num_spot.
indices (2D tensor) – Pairs of spot indices of which to calculate the similarity, 2 x num_pairs.
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.
nonneg (bool) – If True, set negative similarity to 0.
return_type (str) – If sparse, return a sparse tensor. If dense, return a dense tensor. If flat, return a flat tensor of length num_pairs.

Returns:

A 2D tensor containing pairwise similarities, num_spot x num_spot.

Return type:

feature_sim

smoother.weights.calc_feature_similarity(features: torch.Tensor, dist_metric='cosine', reduce='pca', dim=10, nonneg=False)

Calculate pairwise feature similarity between spots.

Similarity s is transformed from distance d by 1) Cosine similarity: s = (1 - d) (if nonneg, (1 - d).clamp(min = 0)) 2) Others: s = exp(- d^2/(2 * band_width^2)))

Parameters:

features (2D tensor) – Feature matrix, num_feature 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.
nonneg (bool) – If True, set negative similarity to 0.

Returns:

A 2D tensor containing pairwise similarities, num_spot x num_spot.

Return type:

feature_sim

smoother.weights.get_histology_vector(image, x_pixel, y_pixel, spot_radius, scale_factor, padding=True)

Get the histology image vector of one spot.

Parameters:

image (3D array) – Histology image, num_pixel x num_pixel x num_channel.
x_pixel (float) – Spot centric position (in fullres).
y_pixel (float) – Spot centric position (in fullres).
spot_radius (float) – Spot size (in fullres).
scale_factor (float) – Scale factor that transforms fullres image to the given image.
paddings (bool) – Whether to pad for boundary spots. If False, will return the averaged color vector.

Returns:

A vector containing histology information around the spot.

Return type:

spot_vec (1D array)

smoother.weights.calc_histology_similarity_sparse(coords, indices, image, scale_factors, dist_metric='euclidean', reduce='none', dim=3, nonneg=True)

Calculate pairwise histology similarity between spots for a given set of points.

Parameters:

coords (2D array) – Spatial coordinate matrix (in fullres pixel), num_spot x 2.
indices (2D tensor) – Pairs of spot indices of which to calculate the similarity, 2 x num_pairs.
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) –
How to compute histological similarity. Can be one of ‘pca’, ‘mean’, and ‘none’. If ‘none’, will concatenate pixel-level histology vectors of each spot and calculate distance. If ‘pca’, will concatenate pixel-level histology vectors of each spot, apply PCA to reduce

the dimension of the histology space, then calculate the distance.

If ‘mean’, will average the histology vector of each spot over its covering area.
dim (int) – Number of dimension of the reduced space.
nonneg (bool) – Whether to remove negative similarity.

Returns:

A 2D tensor containing pairwise histology similarities, num_spot x num_spot.

Return type:

hist_sim

smoother.weights.calc_histology_similarity(coords, image, scale_factors, dist_metric='euclidean', reduce='pca', dim=3, nonneg=True)

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) –
How to compute histological similarity. Can be one of ‘pca’, ‘mean’, and ‘none’. If ‘none’, will concatenate pixel-level histology vectors of each spot and calculate distance. If ‘pca’, will concatenate pixel-level histology vectors of each spot, apply PCA to reduce

the dimension of the histology space, then calculate the distance.

If ‘mean’, will average the histology vector of each spot over its covering area.
dim (int) – Number of dimension of the reduced space.
nonneg (bool) – Whether to remove negative similarity.

Returns:

A 2D tensor containing pairwise histology similarities, num_spot x num_spot.

Return type:

hist_sim

smoother.weights.quantile_feature_similarity_neighbor(features, coords, k, reduce='pca', dim=20, n_null=100)

Calculate cosine similarity of features between physical k-nearest neighbors.

Parameters:

features (2D tensor) – Feature matrix, num_gene x num_spot.
coords (2D tensor) – Coordinates of spots, num_spot x 2.
k (int) – Number of neighbors.
reduce (str) – Dimension reduction method, ‘pca’ or ‘none’.
dim (int) – Number of dimensions to reduce to.
n_null (int) – Number of null distribution samples.

Returns:

Quantiles of cosine similarity between neighbors.

Return type:

df (dataframe)

smoother.weights.quantile_feature_similarity_decay(features, coords, max_k=50, topk=False, reduce='pca', dim=20)

Calculate cosine similarity of features between physical neighbors of varying degrees.

Parameters:

features (2D tensor) – Feature matrix, num_gene x num_spot.
coords (2D tensor) – Coordinates of spots, num_spot x 2.
max_k (int) – Maximum number of neighbors.
topk (bool) – Whether to keep all neighbors within the threshold or only the k nearest neighbors.
reduce (str) – Dimension reduction method, ‘pca’ or ‘none’.
dim (int) – Number of dimensions to reduce to.

Returns:

Quantiles of cosine similarity between neighbors.

Return type:

df (dataframe)

smoother.weights.get_neighbor_quantile_value_by_k(sq_mat, coords, min_k=0, max_k=50)

Extract values of neighboring pairs of spots from the square matrix.

Parameters:

sq_mat (2D tensor) – Data to extract, num_spot x num_spot.
coords (2D tensor) – Coordinates of spots, num_spot x 2.
min_k (int) – Minimum number of neighbors. k = 0: self.
max_k (int) – Maximum number of neighbors.

smoother.weights.plot_similarity_cdf(df_k, title='', k=None)

Plot cumulative distribution of pairwise cosine similarity between neighboring spots.

Parameters:

df_k (dataframe) – Quantiles of cosine similarity between neighbors. Output of quantile_feature_similarity_neighbor.
title (str) – Plot title.
k (int) – Number of neighbors (labeling only).

smoother.weights.plot_similarity_decay(df_all, title='', plot_type='shadow')

Plot decay of pairwise cosine similarity between neighboring spots.

Parameters:

df_all (dataframe) – Quantiles of cosine similarity between neighbors. Output of quantile_feature_similarity_decay.
title (str) – Plot title.
plot_type (str) – Type of plot, “shadow”, “boxplot” or “lineplot”.

smoother.weights._mono_exp(x, alpha, beta)

smoother.weights.estimate_decay_rate(x, y, return_all_params=False)

Estimate decay rate of a mono-exponential decay function.

Parameters:

x (array) – x values.
y (array) – y values.
return_all_params (bool) – If False, only return decay rate (beta).

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

_check_swm_stats(scaled=False) → None: Check spatial weight matrix statistics.

calc_weights_knn(coords, k=6, symmetric=True, row_scale=False) → 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.

calc_weights_dist(coords, scale_coords=True, radius_cutoff=1.0, band_width=0.1, dist_metric='euclidean', row_scale=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.

scale_by_similarity(pairwise_sim: torch.Tensor, row_scale=False, return_swm=False)

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.

scale_by_identity(spot_ids, boundary_connectivity=0, row_scale=False, return_swm=False)

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) → 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.

scale_by_histology(coords, image, scale_factors: dict, dist_metric='euclidean', reduce='pca', dim=10, row_scale=False)

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.

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.