drvi.utils.metrics.most_similar_gap_score

drvi.utils.metrics.most_similar_gap_score(result_matrix)

Compute the most similar gap score for disentanglement evaluation.

This function measures the average gap between the best and second-best scores for each target variable. It quantifies how clearly each target variable is captured by its best-matching dimension penalized by other dimensions.

Parameters:

result_matrix (ndarray) – Matrix of metric scores with shape (n_dimensions, n_categories). Each element [i, j] represents the score for dimension i and category j.

Return type:

float

Returns:

float The average gap between best and second-best scores across all target variables. Higher values indicate clearer dimension-target variable relationships.

Notes

The function computes the difference between the highest and second-highest scores for each target variable, then averages these gaps across all target variables.

Algorithm steps: 1. Sort scores for each target variable in descending order 2. Compute gap between first and second highest scores for each target variable 3. Average the gaps across all target variables

Mathematical formula: ` sorted_scores = sort(result_matrix, axis=0, descending=True) gaps = sorted_scores[0, :] - sorted_scores[1, :] score = mean(gaps) `

Examples

>>> import numpy as np
>>> # Example result matrix (4 dimensions, 3 categories)
>>> result_matrix = np.array(
...     [
...         [0.9, 0.1, 1.0],
...         [0.1, 0.9, 0.1],
...         [0.1, 0.1, 0.9],
...         [0.1, 0.9, 0.1],
...     ]
... )
>>> score = most_similar_gap_score(result_matrix)
>>> print(f"MSGS score: {score:.3f}")  # 0.300