smoother ======== .. py:module:: smoother Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/smoother/losses/index /autoapi/smoother/models/index /autoapi/smoother/simulation/index /autoapi/smoother/utils/index /autoapi/smoother/visualization/index /autoapi/smoother/weights/index Classes ------- .. autoapisummary:: smoother.SpatialWeightMatrix smoother.SpatialLoss smoother.ContrastiveSpatialLoss Package Contents ---------------- .. py:class:: SpatialWeightMatrix Spatial weight matrix. The adjacency matrix that specifies connectivities and interactions between each pair of spots. .. attribute:: swm Unscaled spatial weight matrix. :type: sparse tensor .. attribute:: swm_scaled Spatial weight matrix scaled with external information (e.g., expression, histology). :type: sparse tensor .. attribute:: inv_covs Cached inverse covariance matrices under different model settings (for debugging). :type: dict .. attribute:: config Configurations. :type: dict .. py:attribute:: swm :value: None .. py:attribute:: swm_scaled :value: None .. py:attribute:: inv_covs .. py:attribute:: config .. py:method:: _check_swm_stats(scaled=False, verbose=True) -> None Check spatial weight matrix statistics. .. py:method:: 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. :param coords: Spatial coordinates, num_spot x 2 (or 3). :type coords: 2D array :param k: Number of nearest neighbours to keep. :type k: int :param symmetric: If True only keep mutual neighbors. :type symmetric: bool :param row_scale: If True scale row sum of the spatial weight matrix to 1. :type row_scale: bool :param verbose: If True, print out weights summary. :type verbose: bool .. py:method:: 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. :param coords: Spatial coordinates, num_spot x 2 (or 3). :type coords: 2D array :param scale_coords: If True, scale coordinates to [0, 1]. :type scale_coords: bool :param radius_cutoff: Distance threshold (in the same unit as the coords input). :type radius_cutoff: float :param band_width: Specify the width of the Gaussian kernel, which is proportional to the inverse rate of weight distance decay. :type band_width: float :param dist_metric: Distance metric. :type dist_metric: str :param row_scale: If True scale row sum of the spatial weight matrix to 1. :type row_scale: bool :param verbose: If True, print out weights summary. :type verbose: bool .. py:method:: 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. :param pairwise_sim: External pairwise similarity, num_spot x num_spot. :type pairwise_sim: 2D tensor :param row_scale: If True, scale rowsums of spatial weight matrix to be 1. :type row_scale: bool :param return_swm: Whether to output the scaled spatial weight matrix. :type return_swm: bool :param verbose: If True, print out weights summary. :type verbose: bool .. py:method:: scale_by_identity(spot_ids, boundary_connectivity=0, row_scale=False, return_swm=False, verbose=True) -> None Scale spatial weight matrix by spot identity. :param spot_ids: Spot identity of length num_spot. :type spot_ids: 1D array :param boundary_connectivity: Connectivity of spots with different identities. If 0 (default), no interaction across identities. :type boundary_connectivity: float .. py:method:: scale_by_expr(expr, dist_metric='cosine', reduce='pca', dim=10, row_scale=False, verbose=True) -> None Scale weight matrix using transcriptional similarity. :param expr: Spatial gene expression count matrix, num_genes x num_spot. :type expr: 2D array :param dist_metric: Distance metric. :type dist_metric: str :param reduce: If `PCA`, calculate distance on the reduced PCA space. :type reduce: str :param dim: Number of dimension of the reduced space. :type dim: int :param row_scale: If True, scale rowsums of spatial weight matrix to be 1. :type row_scale: bool :param verbose: If True, print out weights summary. :type verbose: bool .. py:method:: 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. :param coords: Spatial coordinate matrix (in fullres pixel), num_spot x 2. :type coords: 2D array :param image: Histology image, num_pixel x num_pixel x num_channel. :type image: 3D array :param scale_fators: 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. :type scale_fators: dict :param reduce: If `PCA`, calculate distance on the reduced PCA space. :type reduce: str :param dist_metric: Distance metric used to calculate similarity. :type dist_metric: str :param dim: Number of dimension of the reduced space. :type dim: int :param row_scale: If True, scale rowsums of spatial weight matrix to be 1. :type row_scale: bool :param verbose: If True, print out weights summary. :type verbose: bool .. py:method:: get_inv_cov(model, rho=1, cached=True, standardize=False, return_sparse=True) Calculate or extract cached inverse covariance matrix. :param model: The spatial process model, can be one of 'sma','sar', 'car', 'icar'. :type model: str :param rho: The spatial autocorrelation parameter. :type rho: float :param return_sparse: If True, return sparse matrix. :type return_sparse: bool .. py:class:: SpatialLoss(prior, spatial_weights: List[smoother.weights.SpatialWeightMatrix] = None, rho=1, use_sparse=True, standardize_cov=False) Bases: :py:obj:`torch.nn.Module` Spatial loss. The spatial smoothing loss on a spatial random variable (num_group x num_spot). .. attribute:: prior The prior spatial process model, can be one of 'sma','sar', 'car', 'icar'. :type: str .. attribute:: 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] .. attribute:: rho The spatial autocorrelation parameter (for SpatialWeightMatrix.get_inv_cov). :type: float .. attribute:: use_sparse Whether to use sparse inverse covariance matrix in the calculation. :type: bool .. attribute:: standardize_cov Whether to standardize the covariance matrix to have same variance (1) across locations. Only proper covariance can be standardized. :type: bool .. attribute:: 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 .. attribute:: inv_cov_2d_sp Sparse block diagonal inverse covariance (precision) matrix. :type: 2D sparse tensor .. attribute:: 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 .. py:attribute:: prior .. py:attribute:: spatial_weights :value: None .. py:attribute:: rho :value: 1 .. py:attribute:: use_sparse :value: True .. py:attribute:: standardize_cov :value: False .. py:method:: _sanity_check() -> None Check whether the spatial loss is defined properly. .. py:method:: estimate_confidence(ref_exp, st_exp, method='lr') -> None Estimate the relative confidence for each group. The covariance matrix will be scaled accordingly. :param ref_exp: Bulk expression signiture matrix, num_gene x num_group. :type ref_exp: 2D tensor :param st_exp: Spatial expression matrix, num_gene x num_spot. :type st_exp: 2D tensor :param method: Method used to estimate variance. :type method: str .. py:method:: forward(coefs, normalize=True) Calculate spatial loss. :param coefs: Columns of regression coefficients, num_group x num_spot. :type coefs: 2D tensor .. py:method:: 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. :param coords: Coordinates of spots, num_spot x 2. :type coords: 2D tensor :param min_k: Minimum number of k in k-nearest neighbors. k = 0: self. :param max_k: Maximum number of k in k-nearest neighbors. :param cov_ind: Index of the covariance matrix to use. :type cov_ind: int :param return_var: Whether to return variance stats. :type return_var: bool :returns: Correlation decay quantiles. var_quantiles_df (pd.DataFrame): Per-spot variance quantiles. :rtype: corr_decay_quantiles_df (pd.DataFrame) .. py:class:: 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: :py:obj:`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. .. py:attribute:: num_perm :value: 10 .. py:attribute:: neg2pos_ratio :value: 0.5 .. py:attribute:: lower_bound :value: -1 .. py:method:: check_positive_definite(n_tests=10) Check if the covariance matrix is positive semi-definite. .. py:method:: forward(coefs, normalize=True) Calculate contrastive spatial loss.