Silhouette Score

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

# silhouette-score

> Metric `silhouette_score` from `scikit-learn` (sklearn.metrics.silhouette_score)

## When to invoke this skill

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

## Reference signature

```python
from sklearn.metrics import silhouette_score

# silhouette_score(X, labels, *, metric='euclidean', sample_size=None, random_state=None, **kwds)
```

## Library docstring

```
Compute the mean Silhouette Coefficient of all samples.

The Silhouette Coefficient is calculated using the mean intra-cluster
distance (``a``) and the mean nearest-cluster distance (``b``) for each
sample.  The Silhouette Coefficient for a sample is ``(b - a) / max(a,
b)``.  To clarify, ``b`` is the distance between a sample and the nearest
cluster that the sample is not a part of.
Note that Silhouette Coefficient is only defined if number of labels
is ``2 <= n_labels <= n_samples - 1``.

This function returns the mean Silhouette Coefficient over all samples.
To obtain the values for each sample, use :func:`silhouette_samples`.

The best value is 1 and the worst value is -1. Values near 0 indicate
overlapping clusters. Negative values generally indicate that a sample has
been assigned to the wrong cluster, as a different cluster is more similar.

Read more in the :ref:`User Guide <silhouette_coefficient>`.

Parameters
----------
X : {array-like, sparse matrix} of shape (n_samples_a, n_samples_a) if metric ==             "precomputed" or (n_samples_a, n_features) otherwise
    An array of pairwise distances between samples, or a feature array.

labels : array-like of shape (n_samples,)
    Predicted labels for each sample.

metric : str or callable, default='euclidean'
    The metric to use when calculating distance between instances in a
    feature array. If metric is a string, it must be one of the options
    allowed by :func:`~sklearn.metrics.pairwise_distances`. If ``X`` is
    the distance array itself, use ``metric="precomputed"``.

sample_size : int, default=None
    The size of the sample to use when computing the Silhouette Coefficient
    on a random subset of the data.
    If ``sample_size is None``, no sampling is used.

random_state : int, RandomState instance or None, default=None
    Determines random number generation for selecting a subset of samples.
    Used when ``sample_size is not None``.
    Pass an int for reproducible results across multiple function calls.
    See :term:`Glossary <random_state>`.

**kwds : optional keyword parameters
    Any further parameters are passed directly to the distance function.
    If using a scipy.spatial.
```

## Quick recipe

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