Completeness Score

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

# 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

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

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