Completeness Score

completeness-score

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

When to invoke this skill

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

Reference signature

from sklearn.metrics import completeness_score

# completeness_score(labels_true, labels_pred)

Library docstring

Compute completeness metric of a cluster labeling given a ground truth.

A clustering result satisfies completeness if all the data points
that are members of a given class are elements of the same cluster.

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:`homogeneity_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
-------
completeness : float
   Score between 0.0 and 1.0. 1.0 stands for perfectly complete labeling.

See Also
--------
homogeneity_score : Homogeneity 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 complete::

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

Non-perfect labelings that assign all classes members to the same clusters
are still complete::

  >>> print(completeness_score([0, 0, 1, 1], [0, 0, 0, 0]))
  1.0
  >>> print(completeness_score([0, 1, 2, 3], [0, 0, 1, 1]))
  0.999

If classes members are split across different clusters, the
assignment cannot be complete::

  >>> print(completeness_score([0, 0, 1, 1], [0, 1, 0, 1]))
  0.0
  >>> print(completeness_score([0, 0, 0, 0], [0, 1, 2, 3]))
  0.0

Quick recipe

import sklearn.metrics as _m
score = _m.completeness_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).