smoother.losses =============== .. py:module:: smoother.losses .. autoapi-nested-parse:: Transform spatial covariance into spatial loss Classes ------- .. autoapisummary:: smoother.losses.SpatialLoss smoother.losses.TopLoss smoother.losses.ContrastiveSpatialLoss Functions --------- .. autoapisummary:: smoother.losses.kl_loss_scipy smoother.losses.kl_loss smoother.losses.quadratic_loss smoother.losses.sparse_quadratic_loss Module Contents --------------- .. py:function:: kl_loss_scipy(p, weights=None) Calculate KL divergence using scipy. :param p: Probability distributions, num_group x num_spot. Each column is one discrete distribution over num_group groups. :type p: 2D array :param weights: Spatial weight matrix, num_spot x num_spot. If not None, will scale pairwise KL divergence by the weight matrix. :type weights: 2D array :returns: The mean pairwise KL divergence between spots, num_spot x num_spot. :rtype: kl (float) .. py:function:: kl_loss(p, weights=None) Calculate kl divergence using pytorch. :param p: Probability distributions, num_group x num_spot. Each column is one discrete distribution over num_group groups. :type p: 2D array :param weights: Spatial weight matrix, num_spot x num_spot. If not None, will scale pairwise KL divergence by the weight matrix. :type weights: 2D array :returns: The mean pairwise KL divergence between spots, num_spot x num_spot. :rtype: kl (float) .. py:function:: 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. :param beta: Columns of regression coefficients, num_group x num_spot. :type beta: 2D tensor :param 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 inv_cov: 3D tensor :param group_scales: 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 group_scales: 1D tensor or float :param normalize: If True, normalize the likelihood over the size of beta for comparability. :type normalize: bool :returns: Sum of quadratic loss, i.e., the negative likelihood of the corresponding multivariate normal prior on `beta`. :rtype: neg_loglik (float) .. py:function:: 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. :param beta: Columns of regression coefficients, num_group x num_spot. :type beta: 2D tensor :param inv_cov_2d_sp: 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. :type inv_cov_2d_sp: 2D sparse tensor :param group_scales: 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 group_scales: 1D tensor or float :param normalize: If True, normalize the likelihood over the size of beta for comparability. :type normalize: bool :returns: Sum of quadratic loss, i.e., the negative likelihood of the corresponding multivariate normal prior on `beta`. :rtype: neg_loglik (float) .. 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:: TopLoss(betti_priors: dict, coords_xy) Bases: :py:obj:`torch.nn.Module` Topological loss. The topological smoothing loss on a spatial random variable (num_group x num_spot). .. attribute:: betti_prior A nested dictionary that specifies topological priors for each group. {group_id: {betti_k : expectation}}. :type: dict .. attribute:: coords_xy Spatial coordinates (2D), num_spot x 2. :type: 2D array .. attribute:: pdfn Super-level set layer. :type: topologylayer.nn.LevelSetLayer2D .. attribute:: topfn Topological features for each group. {group_id: {betti_k: topologylayer.nn.PartialSumBarcodeLengths}}. :type: dict .. py:attribute:: betti_priors .. py:attribute:: coords_xy .. py:attribute:: _num_spot .. py:attribute:: pdfn .. py:attribute:: topfn .. py:method:: 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`. :param beta: Columns of regression coefficients, num_group x num_spot. :type beta: 2D array :param pad_value: Value of coefficients at unobserved regions. :type pad_value: float .. py:method:: forward(coefs) Calculate topological loss. :param coefs: Columns of regression coefficients, num_group x num_spot. :type coefs: 2D tensor .. 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.