evomap.transform
================

.. py:module:: evomap.transform

.. autoapi-nested-parse::

   Module for transforming lower-dimensional maps post-creation, including alignment and rotation.



Functions
---------

.. autoapisummary::

   evomap.transform.align_maps
   evomap.transform.align_map
   evomap.transform.PCA
   evomap.transform.rotate_map
   evomap.transform.rotate_maps


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

.. py:function:: align_maps(Xs, X_ref, mode='individual')

   Align a sequence of maps to a reference map using Orthogonal Procrustes Analysis.

   :param Xs: List of map coordinates, each of shape (n_samples, n_dims).
   :type Xs: list of ndarray
   :param X_ref: Reference map, shape (n_samples, n_dims).
   :type X_ref: ndarray
   :param mode: Alignment mode:
                - "individual": Align each map independently to the reference.
                - "fixed": Align the first map to the reference and apply the same rotation to all.
   :type mode: str, optional (default="individual")

   :returns: List of aligned maps.
   :rtype: list of ndarray


.. py:function:: align_map(X, X_ref)

   Align a single map to a reference map using Orthogonal Procrustes Analysis.

   :param X: Map coordinates, shape (n_samples, n_dims)
   :type X: ndarray
   :param X_ref: Reference map, shape (n_samples, n_dims)
   :type X_ref: ndarray

   :returns: Aligned map, shape (n_samples, n_dims)
   :rtype: ndarray


.. py:function:: PCA(X, num_components)

   Perform Principal Component Analysis (PCA).

   :param X: Data matrix, shape (n_samples, n_features)
   :type X: ndarray
   :param num_components: Number of principal components to retain
   :type num_components: int

   :returns: Reduced dimensionality data, shape (n_samples, num_components)
   :rtype: ndarray


.. py:function:: rotate_map(Y_2D)

   Rotate a 2D map to align along the direction of maximum variance using PCA.

   :param Y_2D: 2D map, shape (n_samples, 2)
   :type Y_2D: ndarray

   :returns: Rotated map, shape (n_samples, 2)
   :rtype: ndarray


.. py:function:: rotate_maps(Y, inclusions)

   Rotate multiple maps such that the x-axis corresponds to the direction of maximum variance,
   controlled by an inclusion parameter which determines which elements within each map are subject
   to rotation.

   :param Y: List of maps, each map shape (n_samples, n_dims)
   :type Y: list of ndarray
   :param inclusions: List of 0/1 vectors, each vector of length `n_samples` indicating whether the corresponding
                      element in a map should be included in rotation.
   :type inclusions: list of ndarray

   :returns: List of rotated maps, each map shape (n_samples, n_dims)
   :rtype: list of ndarray

   :raises ValueError: If the length of any inclusion vector does not match the number of samples in its corresponding map.