spateo.alignment.methods.morpho_class ===================================== .. py:module:: spateo.alignment.methods.morpho_class Classes ------- .. autoapisummary:: spateo.alignment.methods.morpho_class.Morpho_pairwise Module Contents --------------- .. py:class:: Morpho_pairwise(sampleA: anndata.AnnData, sampleB: anndata.AnnData, rep_layer: Union[str, List[str]] = 'X', rep_field: Union[str, List[str]] = 'layer', genes: Optional[Union[List[str], numpy.ndarray, torch.Tensor]] = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', iter_key_added: Optional[str] = None, save_concrete_iter: bool = False, vecfld_key_added: Optional[str] = None, dissimilarity: Union[str, List[str]] = 'kl', probability_type: Union[str, List[str]] = 'gauss', probability_parameters: Optional[Union[float, List[float]]] = None, label_transfer_dict: Optional[Union[dict, List[dict]]] = None, nn_init: bool = True, init_transform: bool = True, allow_flip: bool = False, init_layer: str = 'X', init_field: str = 'layer', nn_init_top_K: int = 10, nn_init_weight: float = 1.0, max_iter: int = 200, nonrigid_start_iter: int = 80, SVI_mode: bool = True, batch_size: Optional[int] = None, pre_compute_dist: bool = True, sparse_calculation_mode: bool = False, sparse_top_k: int = 1024, lambdaVF: Union[int, float] = 100.0, beta: Union[int, float] = 0.01, K: Union[int, float] = 15, kernel_type: str = 'euc', sigma2_init_scale: Optional[Union[int, float]] = 0.1, sigma2_end: Optional[Union[int, float]] = None, gamma_a: float = 1.0, gamma_b: float = 1.0, kappa: Union[float, numpy.ndarray] = 1.0, partial_robust_level: float = 10, normalize_c: bool = True, normalize_g: bool = False, separate_mean: bool = True, separate_scale: bool = False, dtype: str = 'float32', device: str = 'cpu', verbose: bool = True, guidance_pair: Optional[Union[List[numpy.ndarray], numpy.ndarray]] = None, guidance_effect: Optional[Union[bool, str]] = False, guidance_weight: float = 1.0, use_chunk: bool = False, chunk_capacity: float = 1.0, return_mapping: bool = False) A class to align two spatial transcriptomics AnnData objects using the Spateo alignment algorithm. .. attribute:: sampleA The first AnnData object that acts as the reference. :type: AnnData .. attribute:: sampleB The second AnnData object that acts as the reference. :type: AnnData .. attribute:: rep_layer Representation layer(s) used for alignment. Default is "X". :type: Union[str, List[str]] .. attribute:: rep_field Representation layer field(s) in AnnData to be used for alignment. "layer" means gene expression, "obsm" means embdedding like pca or VAE, "obs" means discrete label annotation. Note that Spateo only accept one label annotation. Defaults to "layer". :type: Union[str, List[str]] .. attribute:: genes List or tensor of genes to be used for alignment. For example, you can input the genes you are interested or spatially variabe genes here. Defaults to None. :type: Optional[Union[List[str], torch.Tensor]] .. attribute:: spatial_key Key in `.obsm` of AnnData corresponding to the spatial coordinates. Defaults to "spatial". :type: str .. attribute:: key_added Key under which the aligned spatial coordinates are added in `.obsm`. Defaults to "align_spatial". :type: str .. attribute:: iter_key_added Key under which to store intermediate iteration results in `.uns`. Defaults to None. :type: Optional[str] .. attribute:: save_concrete_iter Whether to save more concrete intermediate iteration results. Default is False. :type: bool .. attribute:: vecfld_key_added Key under which to store vector field results in `.uns`. Defaults to None. :type: Optional[str] .. attribute:: dissimilarity Measure(s) of pairwise dissimilarity of each observation to be used. Defaults to "kl". :type: Union[str, List[str]] .. attribute:: probability_type Type(s) of probability distribution used. Defaults to "gauss". :type: Union[str, List[str]] .. attribute:: probability_parameters Parameters for the probability distribution. Defaults to None. :type: Optional[Union[float, List[float]]] .. attribute:: label_transfer_dict Dictionary that stores the label transfer probability. Defaults to None. :type: Optional[Union[dict, List[dict]]] .. attribute:: nn_init Whether to use nearest neighbor matching to initialize the alignment. Default is True. :type: bool .. attribute:: allow_flip Whether to allow flipping of coordinates. Default is False. :type: bool .. attribute:: init_layer Layer for initialize alignment. Defaults to "X". :type: str .. attribute:: init_field Layer field for initialize alignment. Defaults to 'layer'. :type: str .. attribute:: nn_init_weight Weight for nn_init guidance. Larger means that the nn_init guidance has more impact on the alignment, vice versa. Default is 1.0. :type: float .. attribute:: nn_init_top_K The number of top K nearest neighbors to consider in the nn_init. Defaults to 10. :type: int, optional .. attribute:: guidance_pair List of guidance pairs for alignment. Default is None. :type: Optional[Union[List[np.ndarray], np.ndarray]] .. attribute:: guidance_effect Effect of guidance for the transformation. Valid value: False, "rigid", "nonrigid", and "both". Default is False. :type: Optional[Union[bool, str]] .. attribute:: guidance_weight Weight for guidance. Larger means that the guidance has more impact on the alignment, vice versa. Default is 1. :type: float .. attribute:: max_iter Maximum number of iterations. Defaults to 200. :type: int .. attribute:: SVI_mode Whether to use Stochastic Variational Inference mode. Default is True. :type: bool .. attribute:: batch_size Size of the mini-batch of SVI. Default is 1000. :type: int .. attribute:: pre_compute_dist Whether to precompute the distance matrix when using SVI mode. This will significantly speed up the calculation process but will also take more (GPU) memory. Default is True. :type: bool .. attribute:: sparse_calculation_mode Whether to use sparse matrix calculation. This will significantly reduce the (GPU) memory but will also slow down the speed. Default is False. :type: bool .. attribute:: sparse_top_k The top k elements to keep in sparse calculation mode. Default is 1024. :type: int .. attribute:: use_chunk Whether to use chunking in calculations. This will reduce the (GPU) memory but will also slow down the speed. Default is False. :type: bool .. attribute:: chunk_capacity Chunk size scale to the chunk_base. :type: float .. attribute:: lambdaVF Regularization parameter for the vector field of the non-rigid transformation. Smaller means that non-rigid deformation gets fewer constraints, then deformation can be larger and more flexible, vice versa. Default is 1e2. Recommended setting range [1e-1, 1e4]. :type: Union[int, float] .. attribute:: beta Length-scale of the SE kernel. Larger means less correlation between points and more flexible non-rigid deformation, and vice versa. Default is 0.01. Recommended setting range [1e-4, 1e0]. :type: Union[int, float] .. attribute:: K Number of sparse inducing points used for Nyström approximation for the kernel. Default is 15. :type: Union[int, float] .. attribute:: kernel_type Type of kernel used. Default is "euc". :type: str .. attribute:: sigma2_init_scale Initial value for the spatial dispersion level. Default is 0.1. :type: Optional[Union[int, float]] .. attribute:: partial_robust_level Robust level of partial alignment. Default is 25. :type: float .. attribute:: normalize_c Whether to normalize spatial coordinates. Default is True. :type: bool .. attribute:: normalize_g Whether to normalize gene expression. Default is True. :type: bool .. attribute:: dtype Data type for computations. Default is "float32". :type: str .. attribute:: device Device used to run the program. Default is "cpu". :type: str .. attribute:: verbose Whether to print verbose messages. Default is True. :type: bool .. py:attribute:: verbose .. py:attribute:: sampleA .. py:attribute:: sampleB .. py:attribute:: rep_layer .. py:attribute:: rep_field .. py:attribute:: genes .. py:attribute:: spatial_key .. py:attribute:: key_added .. py:attribute:: iter_key_added .. py:attribute:: save_concrete_iter .. py:attribute:: vecfld_key_added .. py:attribute:: dissimilarity .. py:attribute:: probability_type .. py:attribute:: probability_parameters .. py:attribute:: label_transfer_dict .. py:attribute:: nn_init .. py:attribute:: init_transform .. py:attribute:: nn_init_top_K .. py:attribute:: max_iter .. py:attribute:: allow_flip .. py:attribute:: init_layer .. py:attribute:: init_field .. py:attribute:: SVI_mode .. py:attribute:: batch_size .. py:attribute:: pre_compute_dist .. py:attribute:: sparse_calculation_mode .. py:attribute:: sparse_top_k .. py:attribute:: beta .. py:attribute:: lambdaVF .. py:attribute:: K .. py:attribute:: kernel_type .. py:attribute:: kernel_bandwidth .. py:attribute:: sigma2_init_scale .. py:attribute:: sigma2_end .. py:attribute:: partial_robust_level .. py:attribute:: normalize_c .. py:attribute:: normalize_g .. py:attribute:: separate_mean .. py:attribute:: separate_scale .. py:attribute:: dtype .. py:attribute:: device .. py:attribute:: guidance_pair .. py:attribute:: guidance_effect .. py:attribute:: guidance_weight .. py:attribute:: use_chunk .. py:attribute:: chunk_capacity .. py:attribute:: nn_init_weight .. py:attribute:: gamma_a .. py:attribute:: gamma_b .. py:attribute:: kappa .. py:attribute:: nonrigid_start_iter .. py:attribute:: return_mapping .. py:method:: run() Run the pairwise alignment process for spatial transcriptomics data. Steps involved: 1. Perform coarse rigid alignment if nearest neighbor (nn) initialization is enabled. 2. Calculate the pairwise distance matrix for representations if pre-computation is enabled or not in SVI mode. 3. Initialize iteration variables and structures. 4. Perform iterative variational updates for alignment, including assignment P, gamma, alpha, sigma2, rigid and non-rigid updates. 5. Retrieve the full cell-cell assignment after the iterative process and calculate the optimal rigid transformation :returns: The final cell-cell assignment matrix. :rtype: np.ndarray .. py:method:: _check() Validate and initialize various attributes for the Morpho_pairwise object. This method performs several checks and initializations, including: - Representation layers and fields in AnnData objects - Spatial keys in AnnData objects - Label transfer dictionaries - Dissimilarity metrics - Probability types and parameters - Initialization layers and fields - Guidance effects :raises ValueError: If any of the validations fail or required attributes are missing. :raises KeyError: If the specified spatial key is not found in the AnnData objects. .. py:method:: _align_preprocess(dtype: str = 'float32', device: str = 'cpu') Preprocess the data for alignment. This method performs several preprocessing steps, including: - Determining the backend (CPU/GPU) for computation. - Extracting common genes from the samples. - Extracting gene expression or representations from the samples. - Checking and generating the label transfer matrix from the dictionary. - Extracting and normalizing spatial coordinates. - Normalizing gene expression if required. - Preprocessing guidance pairs if provided. :param dtype: The data type for computations. Defaults to "float32". :type dtype: str, optional :param device: The device used for computation (e.g., "cpu" or "cuda:0"). Defaults to "cpu". :type device: str, optional :raises AssertionError: If the spatial coordinate dimensions of the samples are different. .. py:method:: _guidance_pair_preprocess() Preprocess the guidance pairs for alignment. This method converts the guidance pairs to the backend type (e.g., NumPy, Torch) and normalizes them if required. The normalization is based on the means and scales of the spatial coordinates. :raises ValueError: If `self.guidance_pair` is not properly formatted. .. py:method:: _normalize_coords() Normalize the spatial coordinates of the samples. This method normalizes the spatial coordinates of the samples to have zero mean and unit variance. It can normalize the coordinates separately or globally based on the provided arguments. :raises AssertionError: If the dimensionality of the coordinates does not match. .. py:method:: _normalize_exps() Normalize the gene expression matrices. This method normalizes the gene expression matrices for the samples if the representation field is 'layer' and the dissimilarity metric is not 'kl'. The normalization ensures that the matrices have a consistent scale across the samples. :raises ValueError: If the normalization scale cannot be calculated. .. py:method:: _initialize_variational_variables() Initialize variational variables for the alignment process. This method sets initial guesses for various parameters, initializes variational variables, and configures the Stochastic Variational Inference (SVI) mode if enabled. :param sigma2_init_scale: Initial scaling factor for sigma2. Defaults to 1.0. :type sigma2_init_scale: float, optional :raises ValueError: If any initialization fails. .. py:method:: _init_probability_parameters(subsample: int = 20000) Initialize probability parameters for the alignment process. This method calculates initial values for probability parameters based on the provided subsampling size and the specified dissimilarity and probability types. :param subsample: The number of subsamples to use for initialization. Defaults to 20000. :type subsample: int, optional :raises ValueError: If an unsupported probability type is encountered. .. py:method:: _construct_kernel(inducing_variables_num, sampling_method) Construct the kernel matrix for the alignment process. This method generates inducing variables from the spatial coordinates, constructs the sparse kernel matrix, and handles different kernel types. It raises an error if the kernel type is not implemented. :param inducing_variables_num: Number of inducing variables to sample. :type inducing_variables_num: int :param sampling_method: Method used for sampling the inducing variables. :type sampling_method: str :raises NotImplementedError: If the specified kernel type is not implemented. .. py:method:: _update_batch(iter: int) Update the batch for Stochastic Variational Inference (SVI). This method updates the batch indices and step size for each iteration during the SVI process. It ensures that the batch permutation is rolled to provide a new batch for each iteration. :param iter: The current iteration number. :type iter: int :raises ValueError: If batch size exceeds the number of available data points. .. py:method:: _coarse_rigid_alignment(n_sampling=20000) Perform coarse rigid alignment between two sets of spatial coordinates. This method performs downsampling, voxelization, and matching pairs construction based on brute force mutual K-nearest neighbors (K-NN). It calculates the similarity distance based on gene expression and performs a coarse alignment using inlier estimation. Optionally, it allows flipping the data for better alignment. :param n_sampling: The number of samples to use for downsampling. Defaults to 20000. :type n_sampling: int, optional :raises ValueError: If any required representation is not found in the AnnData objects. :raises RuntimeError: If coarse rigid alignment fails after reducing top_K. .. py:method:: _save_iter(iter: int) Save the current iteration's alignment results. This method saves the current transformed coordinates and the sigma2 value for the specified iteration. It normalizes the coordinates if normalization is enabled. :param iter: The current iteration number. :type iter: int :raises KeyError: If `key_added` or "sigma2" key is not found in `iter_added`. .. py:method:: _update_assignment_P() Update the assignment matrix P. This method calculates the assignment matrix P, which represents the probability of cells in the sampleB are generated by the cells in sampleA. It considers both spatial and expression / representation distances and updates variational parameters accordingly. :param None: :raises ValueError: If any required representation is not found in the AnnData objects. .. py:method:: _update_gamma() Update the gamma parameter. This method updates the gamma parameter based on the current state of the alignment process. It adjusts gamma using the digamma function (_psi) and ensures that gamma remains within the range [0.01, 0.99]. .. py:method:: _update_alpha() Update the gamma parameter. This method updates the gamma parameter based on the current state of the alignment process. It adjusts gamma using the digamma function (_psi) and ensures that gamma remains within the range [0.01, 0.99]. .. py:method:: _update_nonrigid() Update the non-rigid transformation parameters. This method updates the non-rigid transformation parameters using the current state of the alignment process. It computes the Sigma inverse matrix, the PXB term, and updates the variational parameters for the non-rigid alignment. .. py:method:: _update_rigid() Update the rigid transformation parameters. This method updates the rigid transformation parameters using the current state of the alignment process. It solves for rotation and translation using the SVD formula and incorporates guidance and nearest neighbor initialization if applicable. .. py:method:: _update_sigma2(iter: int) Update the sigma2 parameter. This method updates the sigma2 parameter based on the current state of the alignment process. It ensures that sigma2 remains above a certain threshold to prevent numerical instability. :param iter: The current iteration number. :type iter: int :raises ValueError: If sigma2 is not properly updated. .. py:method:: _get_optimal_R() Compute the optimal rotation matrix R and translation vector t. This method computes the optimal rotation matrix and translation vector for aligning the coordinates of sample A to sample B. It uses the SVD formula to determine the optimal rotation and ensures that the transformation maintains the correct orientation. :raises ValueError: If the SVD decomposition fails or if the determinant check fails. .. py:method:: _wrap_output() Wrap the output after the alignment process. This method denormalizes the aligned coordinates, converts them to numpy arrays, and saves them in the instance. It also prepares a dictionary containing the transformation parameters and metadata if `vecfld_key_added` is not None.