drvi.utils.metrics.latent_matching_score

drvi.utils.metrics.latent_matching_score(result_matrix)

Compute the latent matching score for disentanglement evaluation.

This function finds the optimal one-to-one matching between dimensions and target variables, then computes the average score of the matched pairs. It ensures each dimension is assigned to at most one target variable and vice versa.

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 score of the optimal dimension-category matches. Higher values indicate better disentanglement.

Notes

The function uses the Hungarian algorithm (implemented as minimum weight bipartite matching) to find the optimal assignment between dimensions and target variables.

Mathematical formula: ` row_ind, col_ind = max_weight_full_bipartite_matching(result_matrix) score = mean(result_matrix[row_ind, col_ind]) `

Advantages: - Ensures each dimension is used only once - Mathematically rigorous evaluation of disentanglement

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 = latent_matching_score(result_matrix)
>>> print(f"LMS score: {score:.3f}")  # 0.900