spateo.tools.coarse_align
=========================

.. py:module:: spateo.tools.coarse_align

.. autoapi-nested-parse::

   .. todo:: * @Xiaojieqiu: update with Google style documentation, function typings, tests



Functions
---------

.. autoapisummary::

   spateo.tools.coarse_align.procrustes
   spateo.tools.coarse_align.AffineTrans
   spateo.tools.coarse_align.pca_align
   spateo.tools.coarse_align.align_slices_pca


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

.. py:function:: procrustes(X: numpy.ndarray, Y: numpy.ndarray, scaling: bool = True, reflection: str = 'best') -> Tuple[float, numpy.ndarray, dict]

   A port of MATLAB's `procrustes` function to Numpy.

   This function will need to be rewritten just with scipy.spatial.procrustes and
   scipy.linalg.orthogonal_procrustes later.

   Procrustes analysis determines a linear transformation (translation,
   reflection, orthogonal rotation and scaling) of the points in Y to best
   conform them to the points in matrix X, using the sum of squared errors
   as the goodness of fit criterion.

       d, Z, [tform] = procrustes(X, Y)

   :param X: matrices of target and input coordinates. they must have equal
             numbers of  points (rows), but Y may have fewer dimensions (columns) than X.
             scaling: if False, the scaling component of the transformation is forced
             to 1
   :param Y: matrices of target and input coordinates. they must have equal
             numbers of  points (rows), but Y may have fewer dimensions (columns) than X.
             scaling: if False, the scaling component of the transformation is forced
             to 1
   :param reflection: if 'best' (default), the transformation solution may or may not include
                      a reflection component, depending on which fits the data best. setting
                      reflection to True or False forces a solution with reflection or no reflection
                      respectively.

   :returns:

             the residual sum of squared errors, normalized according to a measure of the scale of X,
                 ((X - X.mean(0))**2).sum()
             Z: the matrix of transformed Y-values
             tform: a dict specifying the rotation, translation and scaling that maps X --> Y
   :rtype: d


.. py:function:: AffineTrans(x: numpy.ndarray, y: numpy.ndarray, centroid_x: float, centroid_y: float, theta: Tuple[None, float], R: Tuple[None, numpy.ndarray]) -> Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

   Translate the x/y coordinates of data points by the translating the centroid to the origin. Then data will be
   rotated with angle theta.

   :param x: x coordinates for the data points (bins). 1D np.array.
   :param y: y coordinates for the data points (bins). 1D np.array.
   :param centroid_x: x coordinates for the centroid of data points (bins).
   :param centroid_y: y coordinates for the centroid of data points (bins).
   :param theta: the angle of rotation. Unit is is in `np.pi` (so 90 degree is `np.pi / 2` and value is defined in the
                 clockwise direction.
   :param R: the rotation matrix. If `R` is provided, `theta` will be ignored.

   :returns: The translation matrix used in affine transformation.
             T_r: The rotation matrix used in affine transformation.
             trans_xy_coord: The matrix that stores the translated and rotated coordinates.
   :rtype: T_t


.. py:function:: pca_align(X: numpy.ndarray) -> Tuple[numpy.ndarray, numpy.ndarray]

   Use pca to rotate a coordinate matrix to reveal the largest variance on each dimension.

   This can be used to `correct`, for example, embryo slices to the right orientation.

   :param X: The input coordinate matrix.

   :returns: The rotated coordinate matrix that has the major variances on each dimension.
             R: The rotation matrix that was used to convert the input X matrix to output Y matrix.
   :rtype: Y


.. py:function:: align_slices_pca(adata: anndata.AnnData, spatial_key: str = 'spatial', inplace: bool = False, result_key: Tuple[None, str] = None) -> None

   Coarsely align the slices based on the major axis, identified via PCA

   :param adata: the input adata object that contains the spatial key in .obsm.
   :param spatial_key: the key in .obsm that points to the spatial information.
   :param inplace: whether the spatial coordinates will be inplace updated or a new key `spatial_.
   :param result_key: when inplace is False, this points to the key in .obsm that stores the corrected spatial
                      coordinates.

   :returns: Nothing but updates the spatial coordinates either inplace or with the `result_key` key based on the major axis
             identified via PCA.