Homogeneity Score

---
name: homogeneity-score
description: Compute the homogeneity_score metric — provided by scikit-learn. Use when the user has predictions and ground-truth and needs to compute homogeneity_score, or asks how to score with homogeneity_score.
metadata:
  skill_kind: metric
  source_lib: scikit-learn
  import_path: sklearn.metrics.homogeneity_score
  source: library_introspection
---

# 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

```python
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

```python
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)`.