V Measure Score

v-measure-score

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

When to invoke this skill

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

Reference signature

from sklearn.metrics import v_measure_score

# v_measure_score(labels_true, labels_pred, *, beta=1.0)

Library docstring

V-measure cluster labeling given a ground truth.

This score is identical to :func:`normalized_mutual_info_score` with
the ``'arithmetic'`` option for averaging.

The V-measure is the harmonic mean between homogeneity and completeness::

    v = (1 + beta) * homogeneity * completeness
         / (beta * homogeneity + completeness)

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 furthermore symmetric: switching ``label_true`` with
``label_pred`` will return the same score value. This can be useful to
measure the agreement of two independent label assignments strategies
on the same dataset when the real ground truth is not known.

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.

beta : float, default=1.0
    Ratio of weight attributed to ``homogeneity`` vs ``completeness``.
    If ``beta`` is greater than 1, ``completeness`` is weighted more
    strongly in the calculation. If ``beta`` is less than 1,
    ``homogeneity`` is weighted more strongly.

Returns
-------
v_measure : float
   Score between 0.0 and 1.0. 1.0 stands for perfectly complete labeling.

See Also
--------
homogeneity_score : Homogeneity metric of cluster labeling.
completeness_score : Completeness metric of cluster labeling.
normalized_mutual_info_score : Normalized Mutual Information.

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 both homogeneous and complete, hence have score 1.0::

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

Labelings that assign all classes members to the same clusters
are complete but not homogeneous, hence 

Quick recipe

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