Homogeneity Score

homogeneity-score

Metric homogeneity_score from scikit-learn (sklearn.metrics.homogeneity_score)

When to invoke this skill

The user has predictions + ground truth and asks to evaluate with homogeneity_score, or mentions sklearn.metrics.homogeneity_score directly, or wants the standard scikit-learn implementation.

Reference signature

from sklearn.metrics import homogeneity_score

# homogeneity_score(labels_true, labels_pred)

Library docstring

Homogeneity metric of a cluster labeling given a ground truth.

A clustering result satisfies homogeneity if all of its clusters
contain only data points which are members of a single class.

This metric is independent of the absolute values of the labels:
a permutation of the class or cluster label values won't change the
score value in any way.

This metric is not symmetric: switching ``label_true`` with ``label_pred``
will return the :func:`completeness_score` which will be different in
general.

Read more in the :ref:`User Guide <homogeneity_completeness>`.

Parameters
----------
labels_true : array-like of shape (n_samples,)
    Ground truth class labels to be used as a reference.

labels_pred : array-like of shape (n_samples,)
    Cluster labels to evaluate.

Returns
-------
homogeneity : float
   Score between 0.0 and 1.0. 1.0 stands for perfectly homogeneous labeling.

See Also
--------
completeness_score : Completeness metric of cluster labeling.
v_measure_score : V-Measure (NMI with arithmetic mean option).

References
----------

.. [1] `Andrew Rosenberg and Julia Hirschberg, 2007. V-Measure: A
   conditional entropy-based external cluster evaluation measure
   <https://aclweb.org/anthology/D/D07/D07-1043.pdf>`_

Examples
--------

Perfect labelings are homogeneous::

  >>> from sklearn.metrics.cluster import homogeneity_score
  >>> homogeneity_score([0, 0, 1, 1], [1, 1, 0, 0])
  1.0

Non-perfect labelings that further split classes into more clusters can be
perfectly homogeneous::

  >>> print("%.6f" % homogeneity_score([0, 0, 1, 1], [0, 0, 1, 2]))
  1.000000
  >>> print("%.6f" % homogeneity_score([0, 0, 1, 1], [0, 1, 2, 3]))
  1.000000

Clusters that include samples from different classes do not make for an
homogeneous labeling::

  >>> print("%.6f" % homogeneity_score([0, 0, 1, 1], [0, 1, 0, 1]))
  0.0...
  >>> print("%.6f" % homogeneity_score([0, 0, 1, 1], [0, 0, 0, 0]))
  0.0...

Quick recipe

import sklearn.metrics as _m
score = _m.homogeneity_score(y_true, y_pred)

Don'ts

• Don't reimplement when the library version handles edge cases (NaN, ties, empty inputs) better than a hand-rolled formula.
• Always check the library version's argument order — sklearn is (y_true, y_pred) while torchmetrics is (preds, target).