smoother.losses

Transform spatial covariance into spatial loss

Classes

`SpatialLoss`	Spatial loss.
`TopLoss`	Topological loss.
`ContrastiveSpatialLoss`	Spatial loss for contrastive learning.

Functions

`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.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

prior

spatial_weights = None

rho = 1

use_sparse = True

standardize_cov = False

_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

betti_priors

coords_xy

_num_spot

pdfn

topfn

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.

num_perm = 10

neg2pos_ratio = 0.5

lower_bound = -1

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

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