evomap.metrics#

Useful functions to evaluate maps.

Module Contents#

Functions#

misalign_score(X_t[, normalize])

Calculate misalignment of a sequence of maps.

align_score(X_t)

Calculate alignment of a sequence of maps.

hitrate_score(X, D[, n_neighbors, inc, input_format])

Calculate Hitrate of nearest neighbor recovery for a single map. The

adjusted_hitrate_score(X, D[, n_neighbors, inc, ...])

Calculate Hitrate of nearest neighbor recovery for a single map, adjusted

avg_hitrate_score(X_t, D_t[, n_neighbors, inc_t, ...])

Calculate average Hitrate of nearest neighbor recovery for a sequence of

avg_adjusted_hitrate_score(X_t, D_t[, n_neighbors, ...])

Calculate average Hitrate of nearest neighbor recovery for a sequence of

persistence_score(X_t)

Calculate persistence of a sequence of maps as the average Pearson
evomap.metrics.misalign_score(X_t, normalize=True)[source]#

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.

Parameters

  • Ys (list of ndarrays, each of shape (n_samples, d)) – Map coordinates.

  • normalize (bool, optional) –

    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.

Returns

Misalignment score, bounded within [0, inf). Lower values indicate better alignment.

Return type

float

evomap.metrics.align_score(X_t)[source]#

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.

Parameters

Ys (list of ndarrays, each of shape (n_samples, d)) – Map coordinates.

Returns

Alignment score, bounded between [-1,1]. Higher values indicate better alignment.

Return type

float

evomap.metrics.hitrate_score(X, D, n_neighbors=10, inc=None, input_format='dissimilarity')[source]#

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

Parameters

  • D (ndarray) – 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).

  • X (ndarray of shape (n_samples, d)) – Map coordinates.

  • n_neighbors (int, optional) – Number of neighbors considered when calculating the hitrate, by default 10

  • inc (ndarray of shape (n_samples,), optional) – Inclusion array, indicating if an object is present (via 0 and 1s), by default None

  • input_format (str, optional) – One of ‘vector’, ‘similarity’, or ‘dissimilarity’, by default ‘dissimilarity’

Returns

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

Return type

float

evomap.metrics.adjusted_hitrate_score(X, D, n_neighbors=10, inc=None, input_format='dissimilarity')[source]#

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

Parameters

  • X (ndarray) – 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).

  • Y (ndarray of shape (n_samples, d)) – Map coordinates.

  • n_neighbors (int, optional) – Number of neighbors considered when calculating the hitrate, by default 10

  • inc (ndarray of shape (n_samples,), optional) – Inclusion array, indicating if an object is present (via 0 and 1s), by default None

  • input_format (str, optional) – One of ‘vector’, ‘similarity’, or ‘dissimilarity’, by default ‘dissimilarity’

Returns

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

Return type

float

evomap.metrics.avg_hitrate_score(X_t, D_t, n_neighbors=10, inc_t=None, input_format='dissimilarity')[source]#

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

Parameters

  • Xs (list of ndarrays) – 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).

  • Ys (list of ndarays, each of shape (n_samples, d)) – _description_

  • n_neighbors (int, optional) – Number of neighbors considered when calculating the hitrate, by default 10

  • Inc_ts (list of ndarays, each of shape (n_samples,), optional) – List of inclusion arrays, indicating if an object is present in a given period (via 0 and 1s), by default None

  • input_format (str, optional) – One of ‘vector’, ‘similarity’, or ‘distance’, by default ‘dissimilarity’

Returns

Average hitrate, bounded between [0,1]. Higher values indicate better recovery.

Return type

float

evomap.metrics.avg_adjusted_hitrate_score(X_t, D_t, n_neighbors=10, inc_t=None, input_format='dissimilarity')[source]#

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.

Parameters

  • Xs (list of ndarrays) – 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).

  • Ys (list of ndarays, each of shape (n_samples, d)) – _description_

  • n_neighbors (int, optional) – Number of neighbors considered when calculating the hitrate, by default 10

  • Inc_ts (list of ndarays, each of shape (n_samples,), optional) – List of inclusion arrays, indicating if an object is present in a given period (via 0 and 1s), by default None

  • input_format (str, optional) – One of ‘vector’, ‘similarity’, or ‘dissimilarity’, by default ‘dissimilarity’

Returns

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

Return type

float

evomap.metrics.persistence_score(X_t)[source]#

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.

Parameters

Ys (list of ndarrays, each of shape (n_samples, 2)) – Map coordinates.

Returns

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

Return type

float