netneurotools.cluster.match_cluster_labels

netneurotools.cluster.match_cluster_labels(source, target)[source]

Align cluster labels in source to those in target.

Uses scipy.optimize.linear_sum_assignment() to match solutions. If source has fewer clusters than target the returned assignments may be discontinuous (see Examples for more information).

Parameters:

source ((N,) array_like) – Cluster labels for N subjects, to be re-labelled
target ((N,) array_like) – Cluster labels for N subjects, to which source is mapped

Returns:

matched – Re-labelled source with cluster assignments “matched” to target

Return type:

(N,) array_like

Examples

>>> from netneurotools import cluster

When cluster labels are perfectly matched but e.g., inverted the function will find a perfect mapping:

>>> a = np.array([1, 1, 1, 0, 0, 0, 0, 0, 0, 0])
>>> b = np.array([0, 0, 0, 1, 1, 1, 1, 1, 1, 1])
>>> cluster.match_cluster_labels(a, b)
array([0, 0, 0, 1, 1, 1, 1, 1, 1, 1])

However, the mapping will work even when cluster assignments between the two solutions aren’t perfectly matched. The function will simply choose a re-labelling that generates the “best” alignment between labels:

>>> a = np.array([0, 0, 0, 2, 2, 2, 2, 1, 1, 1])
>>> b = np.array([1, 1, 1, 0, 0, 0, 0, 0, 0, 0])
>>> cluster.match_cluster_labels(a, b)
array([1, 1, 1, 0, 0, 0, 0, 2, 2, 2])

If the source assignment has fewer clusters than the target the returned values may be discontinuous:

>>> cluster.match_cluster_labels(b, a)
array([0, 0, 0, 2, 2, 2, 2, 2, 2, 2])