: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(Ys, 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(Ys)
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, Y, n_neighbors=10, inc=None, input_type='similarity')
Calculate Hitrate of nearest neighbor recovery for a single map. The
score is averaged across all objects.
:param X: Input data, either a similarity / distance 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_type: One of 'vector', 'similarity', or 'distance', by default 'similarity'
:type input_type: 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, Y, n_neighbors=10, inc=None, input_type='similarity')
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 / distance 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_type: One of 'vector', 'similarity', or 'distance', by default 'similarity'
:type input_type: 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(Ys, Xs, n_neighbors=10, Inc_ts=None, input_type='distance')
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 distance/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_type: One of 'vector', 'similarity', or 'distance', by default 'similarity'
:type input_type: str, optional
:returns: Average hitrate, bounded between [0,1]. Higher values indicate better recovery.
:rtype: float
.. py:function:: avg_adjusted_hitrate_score(Ys, Xs, n_neighbors=10, Inc_ts=None, input_type='distance')
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 distance/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_type: One of 'vector', 'similarity', or 'distance', by default 'similarity'
:type input_type: str, optional
:returns: Average adjusted hitrate, bounded between [0,1]. Higher values
indicate better recovery.
:rtype: float
.. py:function:: persistence_score(Ys)
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