evomap.metrics ============== .. py:module:: evomap.metrics .. autoapi-nested-parse:: Module for evaluating maps. 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 Module Contents --------------- .. py:function:: misalign_score(X_t, normalize=True) Calculate misalignment of a sequence of maps. Misalignment is measured as the average Euclidean distance between objects' subsequent map positions. The final score is averaged across all objects. :param X_t: Map coordinates. :type X_t: list of ndarrays, each of shape (n_samples, n_dims) :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. Cosine similarity measures the cosine of the angle between two vectors, thus providing a scale-invariant metric of similarity. :param X_t: Sequence of map coordinates. :type X_t: list of ndarray, each of shape (n_samples, n_dims) :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 the Hitrate of nearest neighbor recovery for a single map. The score is averaged across all objects. :param X: Map coordinates. :type X: ndarray of shape (n_samples, d) :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 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', indicating the type of the input D, 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 :raises ValueError: If the input dimensions mismatch or unsupported input format is provided. .. py:function:: adjusted_hitrate_score(X, D, n_neighbors=10, inc=None, input_format='dissimilarity') Calculate the Hitrate of nearest neighbor recovery for a single map, adjusted for random agreement. The score is averaged across all objects. :param X: Map coordinates, shape (n_samples, d). :type X: ndarray :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 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. Adjusted hitrate corrects the raw hitrate by the expected hitrate due to chance. :rtype: float :raises ValueError: If parameters are out of expected range or input dimensions mismatch. .. py:function:: avg_hitrate_score(X_t, D_t, n_neighbors=10, inc_t=None, input_format='dissimilarity') Calculate the average Hitrate of nearest neighbor recovery for a sequence of maps. The score is averaged across all maps within the sequence. :param X_t: List of map coordinates for each time period, each of shape (n_samples, d). :type X_t: list of ndarray :param D_t: List of input data matrices for each time period, each 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_t: list of ndarray :param n_neighbors: Number of neighbors considered when calculating the hitrate for each map, by default 10. :type n_neighbors: int, optional :param inc_t: List of inclusion arrays for each time period, each indicating if an object is present (via 0 and 1s), by default None. If provided, each should match the number of samples in the corresponding X and D. :type inc_t: list of ndarray, optional :param input_format: Specifies the input format of D_t, one of 'vector', 'similarity', or 'dissimilarity', by default 'dissimilarity'. :type input_format: str, optional :returns: Average hitrate of nearest neighbor recovery, bounded between [0,1]. Higher values indicate better recovery. :rtype: float :raises ValueError: If there are inconsistencies in array sizes or unsupported input format is specified. .. py:function:: avg_adjusted_hitrate_score(X_t, D_t, n_neighbors=10, inc_t=None, input_format='dissimilarity') Calculate the average Adjusted 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 X_t: List of map coordinates for each time period, each of shape (n_samples, d). :type X_t: list of ndarray :param D_t: List of input data matrices for each time period, each 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_t: list of ndarray :param n_neighbors: Number of neighbors considered when calculating the adjusted hitrate for each map, by default 10. :type n_neighbors: int, optional :param inc_t: List of inclusion arrays for each time period, each indicating if an object is present (via 0 and 1s), by default None. If provided, each should match the number of samples in the corresponding X and D. :type inc_t: list of ndarray, optional :param input_format: Specifies the input format of D_t, one of 'vector', 'similarity', or 'dissimilarity', by default 'dissimilarity'. :type input_format: str, optional :returns: Average adjusted hitrate of nearest neighbor recovery, bounded between [0,1]. Higher values indicate better recovery. :rtype: float :raises ValueError: If there are inconsistencies in array sizes or unsupported input format is specified. .. 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 X_t: Sequence of map coordinates. Each ndarray represents a map at a different time. :type X_t: list of ndarrays, each of shape (n_samples, n_dims) :returns: Persistence score, bounded within (-1,1). Higher positive values indicate higher persistence of map movements across time periods. :rtype: float :raises ValueError: If fewer than two maps are provided or if maps do not have consistent dimensions.