:py:mod:`evomap.transform`
==========================

.. py:module:: evomap.transform

.. autoapi-nested-parse::

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



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


Functions
~~~~~~~~~

.. autoapisummary::

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



.. py:function:: align_maps(Xs, X_ref)

   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

   :returns: List of aligned map coordinates, each of shape (n_samples, n_dims)
   :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.