spateo.alignment.utils
======================

.. py:module:: spateo.alignment.utils


Functions
---------

.. autoapisummary::

   spateo.alignment.utils._iteration
   spateo.alignment.utils.downsampling
   spateo.alignment.utils.generate_label_transfer_prior
   spateo.alignment.utils.group_pca
   spateo.alignment.utils.get_optimal_mapping_relationship
   spateo.alignment.utils.mapping_aligned_coords
   spateo.alignment.utils.mapping_center_coords
   spateo.alignment.utils.get_labels_based_on_coords
   spateo.alignment.utils.solve_RT_by_correspondence
   spateo.alignment.utils.rigid_transformation
   spateo.alignment.utils.split_slice
   spateo.alignment.utils.tps_deformation


Module Contents
---------------

.. py:function:: _iteration(n: int, progress_name: str, verbose: bool = True, start_n: int = 0, indent_level=1)

.. py:function:: downsampling(models: Union[List[anndata.AnnData], anndata.AnnData], n_sampling: Optional[int] = 2000, sampling_method: str = 'trn', spatial_key: str = 'spatial') -> Union[List[anndata.AnnData], anndata.AnnData]

.. py:function:: generate_label_transfer_prior(cat1, cat2, positive_pairs=None, negative_pairs=None)

.. py:function:: group_pca(adatas: List[anndata.AnnData], batch_key: str = 'batch', pca_key: str = 'X_pca', use_hvg: bool = True, hvg_key: str = 'highly_variable', **args) -> None

   Perform PCA on a concatenated set of AnnData objects and store the results back in each individual AnnData.

   Parameters:
   ----------
   adatas : List[AnnData]
       A list of AnnData objects to be concatenated and processed.
   batch_key : str, optional
       The key to distinguish different batches in the concatenated AnnData object (default is 'batch').
   pca_key : str, optional
       The key under which to store the PCA results in each AnnData's `.obsm` attribute (default is 'X_pca').
   use_hvg : bool, optional
       Whether to perform PCA using only highly variable genes (default is True).
   hvg_key : str, optional
       The key under which highly variable genes are marked in `.var` (default is 'highly_variable').
   **args
       Additional arguments to pass to `sc.tl.pca`.

   Raises:
   ------
   ValueError:
       If the specified batch_key already exists in any of the input AnnData objects.
       If no highly variable genes are found when use_hvg is True.


.. py:function:: get_optimal_mapping_relationship(X: numpy.ndarray, Y: numpy.ndarray, pi: numpy.ndarray, keep_all: bool = False)

.. py:function:: mapping_aligned_coords(X: numpy.ndarray, Y: numpy.ndarray, pi: numpy.ndarray, keep_all: bool = False) -> Tuple[dict, dict]

   Optimal mapping coordinates between X and Y.

   :param X: Aligned spatial coordinates.
   :param Y: Aligned spatial coordinates.
   :param pi: Mapping between the two layers output by PASTE.
   :param keep_all: Whether to retain all the optimal relationships obtained only based on the pi matrix, If ``keep_all``
                    is False, the optimal relationships obtained based on the pi matrix and the nearest coordinates.

   :returns:

             Two dicts of mapping_X, mapping_Y, pi_index, pi_value.
                 mapping_X is X coordinates aligned with Y coordinates.
                 mapping_Y is the Y coordinate aligned with X coordinates.
                 pi_index is index between optimal mapping points in the pi matrix.
                 pi_value is the value of optimal mapping points.


.. py:function:: mapping_center_coords(modelA: anndata.AnnData, modelB: anndata.AnnData, center_key: str) -> dict

   Optimal mapping coordinates between X and Y based on intermediate coordinates.

   :param modelA: modelA aligned with center model.
   :param modelB: modelB aligned with center model.
   :param center_key: The key in ``.uns`` that corresponds to the alignment info between modelA/modelB and center model.

   :returns:

             A dict of raw_X, raw_Y, mapping_X, mapping_Y, pi_value.
                 raw_X is the raw X coordinates.
                 raw_Y is the raw Y coordinates.
                 mapping_X is the Y coordinates aligned with X coordinates.
                 mapping_Y is the X coordinates aligned with Y coordinates.
                 pi_value is the value of optimal mapping points.


.. py:function:: get_labels_based_on_coords(model: anndata.AnnData, coords: numpy.ndarray, labels_key: Union[str, List[str]], spatial_key: str = 'align_spatial') -> pandas.DataFrame

   Obtain the label information in anndata.obs[key] corresponding to the coords.


.. py:function:: solve_RT_by_correspondence(X: numpy.ndarray, Y: numpy.ndarray, return_scale: bool = False) -> Union[Tuple[numpy.ndarray, numpy.ndarray], Tuple[numpy.ndarray, numpy.ndarray, float]]

   Solve for the rotation matrix R and translation vector t that best align the points in X to the points in Y.

   :param X: Source points, shape (N, D).
   :type X: np.ndarray
   :param Y: Target points, shape (N, D).
   :type Y: np.ndarray
   :param return_scale: Whether to return the scale factor. Defaults to False.
   :type return_scale: bool, optional

   :returns: If return_scale is False, returns the rotation matrix R and translation vector t.
             If return_scale is True, also returns the scale factor s.
   :rtype: Union[Tuple[np.ndarray, np.ndarray], Tuple[np.ndarray, np.ndarray, float]]


.. py:function:: rigid_transformation(adata, spatial_key, key_added, theta=None, translation=None, inplace=True)

.. py:function:: split_slice(adata, spatial_key, split_num=5, axis=2)

.. py:function:: tps_deformation(adata, spatial_key, key_added, grid_num=2, tps_noise_scale=25, add_corner_points=True, alpha=0.1, inplace=True)