Dunnindex

dunnindex

Metric DunnIndex from torchmetrics (torchmetrics.clustering.DunnIndex)

When to invoke this skill

The user has predictions + ground truth and asks to evaluate with DunnIndex, or mentions torchmetrics.clustering.DunnIndex directly, or wants the standard torchmetrics implementation.

Reference signature

from torchmetrics.clustering import DunnIndex

# DunnIndex(p: float = 2, **kwargs: Any) -> None

Library docstring

Compute `Dunn Index`_.

.. math::
    DI_m = \frac{\min_{1\leq i<j\leq m} \delta(C_i,C_j)}{\max_{1\leq k\leq m} \Delta_k}

Where :math:`C_i` is a cluster of tensors, :math:`C_j` is a cluster of tensors,
and :math:`\delta(C_i,C_j)` is the intercluster distance metric for :math:`m` clusters.

This clustering metric is an intrinsic measure, because it does not rely on ground truth labels for the evaluation.
Instead it examines how well the clusters are separated from each other. The score is higher when clusters are dense
and well separated, which relates to a standard concept of a cluster.

As input to ``forward`` and ``update`` the metric accepts the following input:

- ``data`` (:class:`~torch.Tensor`): float tensor with shape ``(N,d)`` with the embedded data. ``d`` is the
  dimensionality of the embedding space.
- ``labels`` (:class:`~torch.Tensor`): single integer tensor with shape ``(N,)`` with cluster labels

As output of ``forward`` and ``compute`` the metric returns the following output:

- ``dunn_index`` (:class:`~torch.Tensor`): A tensor with the Dunn Index

Args:
    kwargs: Additional keyword arguments, see :ref:`Metric kwargs` for more info.

Example::
    >>> import torch
    >>> from torchmetrics.clustering import DunnIndex
    >>> data = torch.tensor([[0, 0], [0.5, 0], [1, 0], [0.5, 1]])
    >>> labels = torch.tensor([0, 0, 0, 1])
    >>> dunn_index = DunnIndex(p=2)
    >>> dunn_index(data, labels)
    tensor(2.)

Quick recipe

import torchmetrics.clustering as _m
score = _m.DunnIndex(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).