smoother

Subpackages

Submodules

Package Contents

Classes

SpatialWeightMatrix

Spatial weight matrix.

SpatialLoss

Spatial loss.

ContrastiveSpatialLoss

Spatial loss for contrastive learning.
class smoother.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.

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