smoother.losses

Transform spatial covariance into spatial loss

Classes

`SpatialWeightMatrix`	Spatial weight matrix.
`SpatialLoss`	Spatial loss.
`TopLoss`	Topological loss.
`ContrastiveSpatialLoss`	Spatial loss for contrastive learning.

Functions

`get_neighbor_quantile_value_by_k`(sq_mat, coords[, ...])	Extract values of neighboring pairs of spots from the square matrix.
`normalize_minmax`(x[, min_zero, return_scale])	Normalize data to [0, 1] or [-1, 1].
`kl_loss_scipy`(p[, weights])	Calculate KL divergence using scipy.
`kl_loss`(p[, weights])	Calculate kl divergence using pytorch.
`quadratic_loss`(beta, inv_cov, group_scales[, normalize])	Calculate quadratic smoothing loss using torch.
`sparse_quadratic_loss`(beta, inv_cov_2d_sp, group_scales)	Calculate quadratic smoothing loss using torch.sparse.

Module Contents

smoother.losses.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.

class smoother.losses.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.

smoother.losses.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.losses.kl_loss_scipy(p, weights=None)

Calculate KL divergence using scipy.

Parameters:

p (2D array) – Probability distributions, num_group x num_spot. Each column is one discrete distribution over num_group groups.
weights (2D array) – Spatial weight matrix, num_spot x num_spot. If not None, will scale pairwise KL divergence by the weight matrix.

Returns:

The mean pairwise KL divergence between spots, num_spot x num_spot.

Return type:

kl (float)

smoother.losses.kl_loss(p, weights=None)

Calculate kl divergence using pytorch.

Parameters:

p (2D array) – Probability distributions, num_group x num_spot. Each column is one discrete distribution over num_group groups.
weights (2D array) – Spatial weight matrix, num_spot x num_spot. If not None, will scale pairwise KL divergence by the weight matrix.

Returns:

The mean pairwise KL divergence between spots, num_spot x num_spot.

Return type:

kl (float)

smoother.losses.quadratic_loss(beta, inv_cov, group_scales, normalize=True)

Calculate quadratic smoothing loss using torch.

This is the main loss that transforms spatial covariance into spatial loss. It is equivalent to adding a multivariate normal prior with precision matrix inv_cov on beta in a regression setting. See model description for more details.

Parameters:

beta (2D tensor) – Columns of regression coefficients, num_group x num_spot.
inv_cov (3D tensor) – Inverse covariance (precision) matrix of spatial variables of each group, (num_group or 1) x n x n. If the first dimension has length 1, all groups will have the same covariance structure.
group_scales (1D tensor or float) – Relative prior confidence of each group. The higher the confidence, the stronger the smoothing will be. If float, all groups will have the same confidence.
normalize (bool) – If True, normalize the likelihood over the size of beta for comparability.

Returns:

Sum of quadratic loss, i.e., the negative likelihood of the corresponding: multivariate normal prior on beta.

Return type:

neg_loglik (float)

smoother.losses.sparse_quadratic_loss(beta, inv_cov_2d_sp, group_scales, normalize=True)

Calculate quadratic smoothing loss using torch.sparse.

This function uses the sparsity of the inverse covariance matrix to speed up the calculation.

Parameters:

beta (2D tensor) – Columns of regression coefficients, num_group x num_spot.
inv_cov_2d_sp (2D sparse tensor) – Sparse block diagonal inverse covariance (precision) matrix of each group. There are in total (num_group or 1) num_spot x num_spot blocks. If 1, all groups will have the same covariance structure.
group_scales (1D tensor or float) – Relative prior confidence of each group. The higher the confidence, the stronger the smoothing will be. If float, all groups will have the same confidence.
normalize (bool) – If True, normalize the likelihood over the size of beta for comparability.

Returns:

Sum of quadratic loss, i.e., the negative likelihood of the corresponding: multivariate normal prior on beta.

Return type:

neg_loglik (float)

class smoother.losses.SpatialLoss(prior, spatial_weights: List[smoother.weights.SpatialWeightMatrix] = None, rho=1, use_sparse=True, standardize_cov=False)

Bases: torch.nn.Module

Spatial loss.

The spatial smoothing loss on a spatial random variable (num_group x num_spot).

prior

The prior spatial process model, can be one of ‘sma’,’sar’, ‘car’, ‘icar’.

Type:: str

spatial_weights

Spatial weight matrix collection of length num_group or 1. If 1 then all groups will be subject to the same covariance.

Type:: List[SpatialWeightMatrix]

rho

The spatial autocorrelation parameter (for SpatialWeightMatrix.get_inv_cov).

Type:: float

use_sparse

Whether to use sparse inverse covariance matrix in the calculation.

Type:: bool

standardize_cov

Whether to standardize the covariance matrix to have same variance (1) across locations. Only proper covariance can be standardized.

Type:: bool

inv_cov

Inverse covariance (precision) matrix of spatial variables of each group, (num_group or 1) x n x n. If the first dimension has length 1, all groups will have the same covariance structure.

Type:: 3D tensor

inv_cov_2d_sp

Sparse block diagonal inverse covariance (precision) matrix.

Type:: 2D sparse tensor

confidences

Relative prior confidence of each group. The higher the confidence, the stronger the smoothing will be. If float, all groups will have the same confidence.

Type:: 1D tensor or float

_sanity_check() → None: Check whether the spatial loss is defined properly.

estimate_confidence(ref_exp, st_exp, method='lr') → None

Estimate the relative confidence for each group.

The covariance matrix will be scaled accordingly.

Parameters:

ref_exp (2D tensor) – Bulk expression signiture matrix, num_gene x num_group.
st_exp (2D tensor) – Spatial expression matrix, num_gene x num_spot.
method (str) – Method used to estimate variance.

forward(coefs, normalize=True)

Calculate spatial loss.

Parameters:: coefs (2D tensor) – Columns of regression coefficients, num_group x num_spot.

calc_corr_decay_stats(coords, min_k=0, max_k=50, cov_ind=0, return_var=False)

Calculate spatial covariance decay over degree of neighborhoods.

Covariance measured between k-nearest neighbors. If the number of covariance matrices (i.e. self.inv_cov.shape[0]) is larger than 1, use ‘cov_ind’ to select the covariance matrix to use.

Parameters:

coords (2D tensor) – Coordinates of spots, num_spot x 2.
min_k – Minimum number of k in k-nearest neighbors. k = 0: self.
max_k – Maximum number of k in k-nearest neighbors.
cov_ind (int) – Index of the covariance matrix to use.
return_var (bool) – Whether to return variance stats.

Returns:

Correlation decay quantiles. var_quantiles_df (pd.DataFrame): Per-spot variance quantiles.

Return type:

corr_decay_quantiles_df (pd.DataFrame)

class smoother.losses.TopLoss(betti_priors: dict, coords_xy)

Bases: torch.nn.Module

Topological loss.

The topological smoothing loss on a spatial random variable (num_group x num_spot).

betti_prior

A nested dictionary that specifies topological priors for each group. {group_id: {betti_k : expectation}}.

Type:: dict

coords_xy

Spatial coordinates (2D), num_spot x 2.

Type:: 2D array

pdfn

Super-level set layer.

Type:: topologylayer.nn.LevelSetLayer2D

topfn

Topological features for each group. {group_id: {betti_k: topologylayer.nn.PartialSumBarcodeLengths}}.

Type:: dict

reshape_coefs(beta, pad_value: float = None)

Reshape 2D coefficients into 3D and pad with zeros.

The original coefficient matrix has 1 location axis (the first dimension) while the transformed matrix will have 2 location axes (x and y, the first two). Spatial arrangement specified in self.coords_xy.

Parameters:

beta (2D array) – Columns of regression coefficients, num_group x num_spot.
pad_value (float) – Value of coefficients at unobserved regions.

forward(coefs)

Calculate topological loss.

Parameters:: coefs (2D tensor) – Columns of regression coefficients, num_group x num_spot.

class smoother.losses.ContrastiveSpatialLoss(prior='icar', spatial_weights: List[smoother.weights.SpatialWeightMatrix] = None, rho=1, use_sparse=True, standardize_cov=True, num_perm=10, neg2pos_ratio=0.5, lower_bound=-1, check_positive_definite=False)

Bases: SpatialLoss

Spatial loss for contrastive learning.

The spatial loss that maximizes similarity of a spatial random variable (num_group x num_spot) over true neighbors while minimizing similarity over randomly generated neighbors. See Zhu, Hao, Ke Sun, and Peter Koniusz. “Contrastive laplacian eigenmaps.”

Advances in Neural Information Processing Systems 34 (2021).

https://arxiv.org/abs/2201.05493

By default, the inverse covariance matrix generated from prior = ‘icar’ and: rho = 1 is the graph laplacian. Set standardize_cov = True to normalize

the graph laplacian.

Attributes: See SpatialLoss.: num_perm (int): Number of negative graphs (generated by randomly shuffling spots). neg2pos_ratio (float): Relative importance of negative samples to positive samples. lower_bound (float): Lower bound of the loss in case that cov is not positive semi-definite. check_neg_samples (bool): Whether to check if resulting cov is positive definite.

check_positive_definite(n_tests=10): Check if the covariance matrix is positive semi-definite.

forward(coefs, normalize=True): Calculate contrastive spatial loss.