:py:mod:`evomap.metrics`
========================

.. py:module:: evomap.metrics

.. autoapi-nested-parse::

   Useful functions to evaluate maps.



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


Functions
~~~~~~~~~

.. autoapisummary::

   evomap.metrics.misalign_score
   evomap.metrics.align_score
   evomap.metrics.hitrate_score
   evomap.metrics.adjusted_hitrate_score
   evomap.metrics.avg_hitrate_score
   evomap.metrics.avg_adjusted_hitrate_score
   evomap.metrics.persistence_score



.. py:function:: misalign_score(X_t, normalize=True)

   Calculate misalignment of a sequence of maps.

   Misaligned is measured as the average Euclidean distance
   between objects' subsequent map positions. The final score is averaged across
   all objects.

   :param Ys: Map coordinates.
   :type Ys: list of ndarrays, each of shape (n_samples, d)
   :param normalize: If true, misalignment is normalized by the average interobject distance
                     on the map. Useful for comparing maps across differently scaled coordinate
                      systems, by default True.
   :type normalize: bool, optional

   :returns: Misalignment score, bounded within [0, inf).
             Lower values indicate better alignment.
   :rtype: float


.. py:function:: align_score(X_t)

   Calculate alignment of a sequence of maps.

   Alignment is measured as the mean cosine similarity of objects' subsequent
   map positions. The final score is averaged across all objects.

   :param Ys: Map coordinates.
   :type Ys: list of ndarrays, each of shape (n_samples, d)

   :returns: Alignment score, bounded between [-1,1].
             Higher values indicate better alignment.
   :rtype: float


.. py:function:: hitrate_score(X, D, n_neighbors=10, inc=None, input_format='dissimilarity')

   Calculate Hitrate of nearest neighbor recovery for a single map. The
   score is averaged across all objects.

   :param D: Input data, either a similarity / dissimilarity matrix of shape
             (n_samples, n_samples), or a matrix of feature vectors of shape (n_samples, d_input).
   :type D: ndarray
   :param X: Map coordinates.
   :type X: ndarray of shape (n_samples, d)
   :param n_neighbors: Number of neighbors considered when calculating the hitrate, by default 10
   :type n_neighbors: int, optional
   :param inc: Inclusion array, indicating if an object is present (via 0 and 1s), by default None
   :type inc: ndarray of shape (n_samples,), optional
   :param input_format: One of 'vector', 'similarity', or 'dissimilarity', by default 'dissimilarity'
   :type input_format: str, optional

   :returns: Hitrate of nearest neighbor recovery, bounded within [0,1].
             Higher values indicate better recovery.
   :rtype: float


.. py:function:: adjusted_hitrate_score(X, D, n_neighbors=10, inc=None, input_format='dissimilarity')

   Calculate Hitrate of nearest neighbor recovery for a single map, adjusted
   for random agreement. The score is averaged across all objects.

   :param X: Input data, either a similarity / dissimilarity matrix of shape
             (n_samples, n_samples), or a matrix of feature vectors of shape (n_samples, d_input).
   :type X: ndarray
   :param Y: Map coordinates.
   :type Y: ndarray of shape (n_samples, d)
   :param n_neighbors: Number of neighbors considered when calculating the hitrate, by default 10
   :type n_neighbors: int, optional
   :param inc: Inclusion array, indicating if an object is present (via 0 and 1s), by default None
   :type inc: ndarray of shape (n_samples,), optional
   :param input_format: One of 'vector', 'similarity', or 'dissimilarity', by default 'dissimilarity'
   :type input_format: str, optional

   :returns: Adjusted Hitrate of nearest neighbor recovery, bounded within [0,1].
             Higher values indicate better recovery.
   :rtype: float


.. py:function:: avg_hitrate_score(X_t, D_t, n_neighbors=10, inc_t=None, input_format='dissimilarity')

   Calculate average Hitrate of nearest neighbor recovery for a sequence of
   maps. The score is averaged across all maps within the sequence.

   :param Xs: Input data, either in the form of dissimilarity/similarity matrices, each of
              shape (n_samples, n_samples), or or feature vectors of shape (n_samples, d_input).
   :type Xs: list of ndarrays
   :param Ys: _description_
   :type Ys: list of ndarays, each of shape (n_samples, d)
   :param n_neighbors: Number of neighbors considered when calculating the hitrate, by default 10
   :type n_neighbors: int, optional
   :param Inc_ts: List of inclusion arrays, indicating if an object is present in a
                  given period (via 0 and 1s), by default None
   :type Inc_ts: list of ndarays, each of shape (n_samples,), optional
   :param input_format: One of 'vector', 'similarity', or 'distance', by default 'dissimilarity'
   :type input_format: str, optional

   :returns: Average hitrate, bounded between [0,1]. Higher values indicate better recovery.
   :rtype: float


.. py:function:: avg_adjusted_hitrate_score(X_t, D_t, n_neighbors=10, inc_t=None, input_format='dissimilarity')

   Calculate average Hitrate of nearest neighbor recovery for a sequence of
   maps, adjusted for random agreement. The score is averaged across all
   maps within the sequence.

   :param Xs: Input data, either in the form of dissimilarity/similarity matrices, each of
              shape (n_samples, n_samples), or or feature vectors of shape (n_samples, d_input).
   :type Xs: list of ndarrays
   :param Ys: _description_
   :type Ys: list of ndarays, each of shape (n_samples, d)
   :param n_neighbors: Number of neighbors considered when calculating the hitrate, by default 10
   :type n_neighbors: int, optional
   :param Inc_ts: List of inclusion arrays, indicating if an object is present in a
                  given period (via 0 and 1s), by default None
   :type Inc_ts: list of ndarays, each of shape (n_samples,), optional
   :param input_format: One of 'vector', 'similarity', or 'dissimilarity', by default 'dissimilarity'
   :type input_format: str, optional

   :returns: Average adjusted hitrate, bounded between [0,1]. Higher values
             indicate better recovery.
   :rtype: float


.. py:function:: persistence_score(X_t)

   Calculate persistence of a sequence of maps as the average Pearson
   correlation coefficient between objects' subsequent map movements (i.e., the
   first differences of their map positions). The score is averaged across all
   objects.

   :param Ys: Map coordinates.
   :type Ys: list of ndarrays, each of shape (n_samples, 2)

   :returns: Persistence score, bounded within (-1,1).
             Higher positive values indicate higher persistence.
   :rtype: float